Agents

Agents are named workflow bundles. An agent can carry its own system prompt, provider and model preferences, tool permissions, MCP servers, shell allowlists, and turn limits.

That means you can stop restating the same intent over and over. Use @reviewer when you want review behavior, @codebase when you want repository exploration, @web-researcher when you want web-backed investigation, and so on.

Using agents

Use the @agent prefix syntax or --agent flag:

term-llm ask @reviewer "review this code" -f main.go
term-llm chat @codebase
term-llm ask --agent web-researcher "Find info about Go 1.24"

Built-in agents

List them anytime with:

term-llm agents list --builtin

term-llm ships with these built-in agents:

A few good starting points:

• @reviewer for code review without letting the model edit files
• @codebase for architecture questions and tracing behavior across a repo
• @developer when you want implementation work done
• @web-researcher when the answer depends on current web information
• @commit-message when you want a clean commit message without fuss

Managing agents

term-llm agents                              # List all agents
term-llm agents list                         # Same as above
term-llm agents list --builtin               # Only built-in agents
term-llm agents list --local                 # Only local agents
term-llm agents list --user                  # Only user agents
term-llm agents new my-agent                 # Create new agent
term-llm agents show reviewer                # Show agent configuration
term-llm agents edit reviewer                # Edit agent configuration
term-llm agents copy reviewer my-reviewer    # Copy an agent to customize
term-llm agents path                         # Print agents directory
term-llm agents export reviewer              # Export an agent bundle
term-llm agents import ./agent-dir           # Import an agent bundle
term-llm agents gist reviewer                # Publish agent as a gist
term-llm agents set reviewer provider=openai model=gpt-5.2
term-llm agents get reviewer
term-llm agents clear reviewer model

Customizing built-ins

A filesystem agent with the same name as a built-in shadows the built-in. For example, to customize the default developer behavior, create term-llm-agents/developer/agent.yaml in a project or ~/.config/term-llm/agents/developer/agent.yaml for your user account. You can start from the bundled implementation with:

term-llm agents copy developer developer      # copy built-in developer into your user agents dir
term-llm agents copy developer my-developer   # fork it under a new name instead

Per-agent preferences in your main config can override provider/model choices without copying an agent bundle:

term-llm agents set reviewer provider=openai model=gpt-5.2

The special agent model value fast resolves through the active provider’s fast-model settings: providers.<active>.fast_model, or providers.<active>.fast_provider plus fast_model when the lightweight model should run on a different provider key. It is not sent to the provider as a literal model named fast.

Built-in developer can spawn up to three subagents in parallel. Its built-in spawn configuration runs spawned codebase subagents with model: fast, so developer-led repository investigations use the lightweight model without changing direct @codebase sessions:

spawn:
  agent_models:
    codebase: fast

Agent configuration

Agents are YAML files stored in ~/.config/term-llm/agents/:

# ~/.config/term-llm/agents/reviewer/agent.yaml
name: reviewer
description: Reviews code for best practices and potential issues

provider: anthropic
model: claude-sonnet-4-6

tools:
  enabled: [read_file, grep, glob]
  # OR use a denylist instead:
  # disabled: [shell, write_file]

shell:
  allow: ["git *", "npm test"]  # glob patterns for allowed commands
  auto_run: true                   # skip confirmation for matched commands
  scripts:                         # named shortcuts (auto-approved)
    build: "npm run build"

search: true   # enables web_search and read_url tools
max_turns: 50   # agentic loop limit; CLI --max-turns overrides this

mcp:
  - name: github

Built-in agents that currently default to search: true: agent-builder, web-researcher, developer, editor, shell, contain.

Structured ask output

Use output_tool when an agent must return a machine-consumable artifact to term-llm ask instead of relying on freeform prose. In ask, a configured output tool is the agent’s final return channel: successful completion requires the model to call that tool and provide the configured parameter. If the model naturally finishes without calling it, ask runs a constrained finalization pass that preserves the original tool context, forces the output tool when the provider supports named tool choice, and otherwise strongly instructs the model that the task is done and it must call the output tool. If the tool still is not called, ask fails nonzero and does not run on_complete.

name: scanner

tools:
  enabled: [read_file, grep, glob]

output_tool:
  name: submit_result
  param: result_json
  description: "Submit the final scanner result as JSON"

on_complete: |
  jq -e . > result.json

on_complete receives the captured output-tool value on stdin. When output_tool is configured, ask never falls back to passing assistant prose to on_complete; validate formats such as JSON in your handler if you need schema guarantees.

output_tool is ignored in term-llm chat. Chat is an open-ended conversation with no single final return value; use ask for tool-captured output.

Platform developer messages

When term-llm serves an agent on different platforms (web UI, Telegram, CLI chat, background jobs), each platform may need different behavioral guidance. The platform_messages block in agent.yaml lets you inject a developer-role message at the start of every new session, keyed by platform.

platform_messages:
  web_developer_message: |
    You are running in the web UI. Use markdown, tables, and links freely.
  telegram_developer_message: |
    You are running as a Telegram bot. Keep responses short.
  chat_developer_message: |
    You are running in CLI chat mode.
  jobs_developer_message: |
    You are running as a background job. Do not prompt for input.

Supported platform keys:

Messages are injected as developer role messages before the first user turn. If no message is configured for the active platform, nothing is injected. Each key is optional. Define only the platforms you need.

System prompt file includes

System prompts support inline file includes with {{file:...}}.

You are a reviewer.

{{file:prompts/rules.md}}
{{file:/absolute/path/to/shared-context.md}}

Behavior:

• Includes are expanded recursively (max depth: 10)
• Cycles are detected and reported as errors
• Missing/unreadable include files fail fast
• Included content is inserted raw (no automatic headers/separators)
• Relative paths are source-relative:
  • Agent prompts resolve relative to the agent directory
  • Config/CLI system prompts resolve relative to the current working directory
• Expansion order is include first, then template variables (for example {{year}})

Agent search order: project-local agents (./term-llm-agents) → user agents (~/.config/term-llm/agents) → configured agents.search_paths → built-in agents