Simple Agent

Simple Agent aims to be a simple, transparent, general-purpose agent TUI.

Features

• Transparency: observe every tool call and agent decision with ease
• Markdown-driven subagents: build modular agents from simple markdown files
• Token-efficient tool calling: optimized tool execution to reduce overhead
• CLI-first design: built for command-line use, with optional non-interactive mode
• API integration: works with OpenAI, Anthropic, and Google Gemini APIs

Installation and Usage

Quick install (recommended)

./install.sh

Usage method 1: shell wrapper (recommended for development)

./agent.sh "your message here"
./agent.sh --agent <agent-type>  # defines the starting agent
./agent.sh --continue            # continue previous session
./agent.sh --user-interface console
./agent.sh --system-prompt       # print rendered system prompt
./agent.sh --stub                # run against the built-in LLM stub
./agent.sh --non-interactive     # suppress interactive prompts

Usage method 2: invoke the script with uv

uv run --project . --script simple_agent/main.py "your message here"
uv run --project . --script simple_agent/main.py --help

Install globally with uv

uv tool install .
agent "your message here"

Examples

# Start an interactive session using the default textual UI
./agent.sh "say hello"

# Run in the console UI and continue the previous session
./agent.sh --user-interface console --continue

Run in a browser (Docker)

The Textual UI can be served in a browser using textual-serve (via serve_web.py).

# Build and run
docker compose up -d --build

# Example .env entries
SIMPLE_AGENT_PUBLIC_URL=http://<host>:8000
ANTHROPIC_API_KEY=...
OPENAI_API_KEY=...
GEMINI_API_KEY=...

Then open http://<host>:8000 in your browser.

Configuration

Create a .simple-agent.toml file either in your home directory or in the directory where you run the agent. Values from the current directory override those from ~.

[model]
default = "claude"  # Which model configuration to use by default

[models.claude]
model = "claude-sonnet-4-5-20250929"
adapter = "claude"
api_key = "${ANTHROPIC_API_KEY}"  # Or use a literal API key

The [model] section specifies which model to use by default. Define one or more models under [models.*] sections. API keys can reference environment variables using ${VAR_NAME} syntax.

Multiple models

You can define multiple model configurations and switch between them:

[model]
default = "claude"

[models.claude]
model = "claude-sonnet-4-5-20250929"
adapter = "claude"
api_key = "${ANTHROPIC_API_KEY}"

[models.openai]
model = "gpt-4o"
adapter = "openai"
api_key = "${OPENAI_API_KEY}"
# base_url = "https://openrouter.ai/api/v1"  # Optional: for OpenRouter, etc.

[models.gemini]
model = "gemini-2.5-pro"
adapter = "gemini"
api_key = "${GOOGLE_API_KEY}"

Adapter-specific configuration

OpenAI adapter: You can point the client at a compatible provider by overriding base_url, e.g. set it to https://openrouter.ai/api/v1 for OpenRouter.

Gemini adapter: Configure with a Google AI API key and model name (e.g., gemini-2.5-pro, gemini-1.5-flash).

Custom agent definitions

Agent definition files (*.agent.md) are discovered from the built-in simple_agent package and from .simple-agent/agents in your project directory. To point the agent at a different directory, add this to .simple-agent.toml:

[agents]
path = "${APP_DIR}/custom_agents"

Example custom agent definition (save as marketing.agent.md in your configured agents directory):

---
name: Marketing
tools:
  - bash
  - cat
  - edit_file
model: gemini-3-flash-preview
---

You are a marketing-focused assistant who writes short, punchy summaries.

{{DYNAMIC_TOOLS_PLACEHOLDER}}

{{AGENTS.MD}}

To change which agent starts first, set it via the [agents] section:

[agents]
start = "orchestrator"

Development

# Run tests
./test.sh                    # Run all tests (stops on first failure)
./test.sh test_foo.py        # Run a specific test file
./test.sh test_foo           # Run tests matching a pattern
./test.sh -v                 # Verbose mode with full tracebacks
./test.sh -h                 # Show help

# Approve received files
./approve.sh

# Generate coverage locally and refresh the badges
./coverage.sh               # generate code coverage report
./coverage.sh foo.py        # show coverage of a specific file
./coverage.sh --badge       # update the coverage badge

Bridge

The bridge allows agents to interact with simple-agent end to end via the file system. It captures the TUI state into a Markdown file and reads your input from a text file. This is useful for building custom integrations or observing the agent without a terminal.

See the Bridge Documentation for details.

Text-to-Speech setup

The say.py script requires a Piper TTS voice model to function. Download the required model:

# Download the voice model (61MB)
curl -L -o en_US-lessac-medium.onnx "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/medium/en_US-lessac-medium.onnx"
curl -L -o en_US-lessac-medium.onnx.json "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json"

Or use the provided script:

./download_voice_model.sh

Then use:

./say.py "Hello world"
# or
./say.sh "Hello world"