Steward is a Python CLI harness for running LLMs with a Copilot-style toolset. It is developed primarily against Azure OpenAI but also supports OpenAI-compatible hosts and a local echo provider, and was in itself bootstrapped by a bun version.

1. Install:

# From GitHub
pip install git+https://github.com/rcarmo/python-steward.git

# Or clone and install locally (editable)
git clone https://github.com/rcarmo/python-steward.git
cd python-steward
python3 -m pip install -e .

2. Run (echo provider, default):

python3 -m steward.cli "List files in the workspace"

3. Run with Azure (set your env vars, options first):

STEWARD_AZURE_OPENAI_ENDPOINT=... \
STEWARD_AZURE_OPENAI_KEY=... \
STEWARD_AZURE_OPENAI_DEPLOYMENT=... \
python3 -m steward.cli --provider azure --model gpt-4o-mini "Read README and summarize"

4. Optional sandbox (auto mkdir + chdir):

python3 -m steward.cli --sandbox sandbox --provider azure --model gpt-4o-mini "List files"

• --provider <echo|openai|azure> (default: echo unless overridden by STEWARD_PROVIDER or Makefile wrapper)
• --model <name> (default: gpt-4o-mini unless overridden by STEWARD_MODEL or Makefile wrapper)
• --max-steps <n> (default from config)
• --timeout-ms <n> per LLM call
• --retries <n> LLM retries
• --log-json <file> / --no-log-json
• --quiet (suppress human logs) / --pretty (color logs)
• --system <file> custom system prompt
• --sandbox [dir] run inside/create a sandbox directory
• --session [id] enable session persistence with checkpoints (auto-generates ID if not specified)
• --instructions <file> load custom coding instructions to inject into system prompt

You can provide your own system prompt via --system; no default file is bundled.

Prefix your prompt with [[PLAN]] to enter plan mode, which instructs the agent to:

• Analyze the codebase and create a structured implementation plan
• Save the plan to the session's plan.md file
• Wait for explicit approval before implementing

python3 -m steward.cli --session "[[PLAN]] Add user authentication to the API"

Steward can run as an MCP (Model Context Protocol) server over stdio, exposing all tools to MCP-compatible clients:

python3 -m steward.mcp   # or: steward-mcp

See docs/protocols.md for configuration examples.

Steward can run as an ACP (Agent Control Protocol) agent over stdio, providing streaming, tool visibility, session management, and more:

python3 -m steward.acp   # or: steward-acp

See docs/protocols.md for full ACP feature documentation.

Steward can consume tools from external MCP servers. Configure in .steward/mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "npx", 
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": { "GITHUB_TOKEN": "your-token" }
    }
  }
}

Tools: mcp_list_servers, mcp_list_tools, mcp_call

When MCP servers are configured, Steward also supports a two-tool Code Mode flow:

• search — runs JavaScript against globalThis.manifest (discovery only; toolbox calls are disabled)
• execute — runs JavaScript with globalThis.toolbox enabled for MCP tool execution

toolbox API:

• toolbox.callTool(server, tool, args)
• toolbox.server("name").category.tool(args)

Example search code:

JSON.stringify(
  manifest.servers.map((s) => ({
    name: s.name,
    categories: Object.keys(s.categories),
  }))
)

Example execute code:

JSON.stringify(
  toolbox.server("github").issues.list({ owner: "octocat", repo: "Hello-World" })
)

The default system prompt includes:

• Tone and style guidance (concise, direct responses)
• Parallel tool calling instructions for efficiency
• Tool-specific usage guidance
• Code change rules (minimal modifications, run tests)
• Security and privacy constraints
• Session and plan mode support
• Environment context (CWD, git root)

Custom instructions can be injected via --instructions <file>.

• Echo: --provider echo (no credentials)
• OpenAI-compatible: --provider openai with STEWARD_OPENAI_API_KEY/OPENAI_API_KEY and optional STEWARD_OPENAI_BASE_URL
• Azure OpenAI: --provider azure with STEWARD_AZURE_OPENAI_ENDPOINT, STEWARD_AZURE_OPENAI_KEY, STEWARD_AZURE_OPENAI_DEPLOYMENT, optional STEWARD_AZURE_OPENAI_API_VERSION (default 2024-10-01-preview)

• Path access is constrained to the current working directory (or sandbox when provided).
• The run loop stops after max steps even if the model keeps calling tools.
• bash is gated by STEWARD_ALLOW_EXECUTE=1 and supports allow/deny lists, timeouts, and audit logging.

• make install — pip install -e .
• make test — python -m pytest tests
• make scenario — sample run in current workspace (uses provider/model defaults)
• make inception — sample run inside sandbox/ using --sandbox

• Improve logging ergonomics
• Add MCP support (stdio transport)
• Add interactive shell I/O tools
• Add session management and plan mode
• Add REPL
• Add streaming support (via ACP)
• Add sub-agent orchestration
• Additional provider shims as needed