agencode

agencode is a keyboard-first terminal workspace for multi-agent coding, file operations, subagent management, and skills-driven automation.

It ships as a Python CLI with:

• a Textual TUI for day-to-day use
• a DeepAgents + LangGraph runtime
• project-local state under .agencode/
• saved subagents managed under a single supervisor agent
• built-in local filesystem and shell execution support
• Skills CLI integration for browsing and installing agent skills

What You Get

• Project-local workspace sessions
  • Running agencode tui inside a folder creates .agencode/ there on first run.
  • That folder stores project config, sessions, saved subagents, and local skill state.
• Keyboard-first TUI
  • Inline terminal mode by default
  • command palette
  • slash commands
  • history loading
  • per-thread skill attachment
• Supervisor + subagents model
  • one top-level supervisor-agent
  • user-created saved subagents attached under the supervisor
  • subagent creation and editing from the TUI
• Skills integration
  • browse and search marketplace skills
  • install skills through npx skills
  • attach skills to subagents
  • attach skills temporarily to a single thread
• Human-in-the-loop safety
  • plan mode
  • approval mode
  • preflight prompts for risky/destructive actions
  • retry/input prompts when the runtime needs user guidance

Install

pip install agencode

Then run:

agencode --help
agencode tui

First Run

Run agencode tui inside the project you want to work on:

cd /path/to/project
agencode tui

On first run, agencode creates:

/path/to/project/.agencode/

That directory contains project-local state such as:

• .agencode/config.toml
• .agencode/agents/
• .agencode/sessions/
• .agencode/skills/

This means each project can keep its own local agent setup and session history.

TUI Basics

Inside the TUI:

• type a prompt and press Enter
• use slash commands for management flows
• use Ctrl+K for the command palette
• use Esc to interrupt a running agent
• use Ctrl+C to copy selected text
• use Ctrl+V to paste into the prompt

If you click around the UI and start typing, focus returns to the prompt automatically.

TUI Slash Commands

Session and context

• /resume
  • Resume the latest thread or a selected previous thread.
• /history
  • Open the thread picker and load a past conversation into the transcript.
• /fork
  • Fork the current thread into a new thread.
• /reset
  • Reset the current session back to a fresh default thread.
• /compact
  • Summarize the current chat into a compact session note for later prompts.
• /mention <path>
  • Attach a file or folder as extra prompt context.
• @path
  • Use path autocomplete in the prompt and attach on send.

Agent and execution control

• /agent
  • Open the subagent manager.
• /build
  • Build the selected agent graph.
• /plan on|off
  • Enable or disable strict plan-first execution mode.
• /permissions auto|confirm|read-only
  • Control approval behavior.
• /personality concise|collaborative|direct
  • Change shell response style.
• /status
  • Show active agent, thread, model, and config status.
• /cancel
  • Dismiss a waiting-for-input prompt.
• /clear
  • Clear the visible conversation pane.
• /refresh
  • Reload agent/runtime state.

Skills

• /skills
  • Open the skills browser and manager.
• /select-skill
  • Attach one or more skills to only the current thread.

Project and inspection

• /diff
  • Show the current git diff in a structured format.
• /init
  • Generate a project-aware AGENTS.md file in the workspace.
• /model
  • Open model/provider settings.
• /theme
  • Switch theme.
• /mcp
  • Open the MCP manager.

Skills Workflow

agencode integrates with the official Skills CLI and treats it as the backend.

The TUI can:

• browse starter categories
• search skills with npx skills find <query>
• install skills
• view installed skills
• check for updates
• update installed skills

Installed skills can then be attached:

• permanently to a saved subagent
• temporarily to the current thread with /select-skill

Subagents

The runtime uses a single supervisor model:

• supervisor-agent

Under that supervisor, you can create your own saved subagents from the TUI.

Subagent workflow:

1. /agent
2. Create New Subagent
3. enter name
4. enter system prompt
5. optionally attach skills
6. review
7. confirm

Each saved subagent can be:

• edited manually
• refined through AI chat
• activated or deactivated
• assigned attached skills
• deleted

The supervisor also has structured internal tools for:

• listing saved subagents
• saving subagents
• activating subagents
• listing attachable skills
• searching marketplace skills
• installing marketplace skills

Human-in-the-Loop Behavior

The TUI is designed to pause and ask for guidance when needed.

Examples:

• destructive requests
• permission-sensitive operations
• root or sudo-adjacent actions
• missing input or blocked execution

The app can ask you to:

• continue
• dry run first
• show commands only
• manual only
• revise the plan

Current CLI Commands

Run agencode --help for the current command list.

Main shipped commands:

• agencode tui
• agencode init-config
• agencode doctor
• agencode config-openai
• agencode config-show
• agencode mcp-list
• agencode mcp-add-stdio
• agencode mcp-add-http
• agencode mcp-bootstrap-defaults
• agencode agent-list
• agencode agent-show
• agencode agent-save-prebuilt
• agencode agent-build-check
• agencode agent-run-prompt
• agencode session-show
• agencode session-list
• agencode skill-list
• agencode skill-show
• agencode skill-install

Common Usage

Launch in the current project

cd /path/to/project
agencode tui

Open a specific workspace

agencode tui --workspace /path/to/project

Configure an OpenAI-compatible provider

agencode config-openai \
  --base-url https://api.openai.com/v1 \
  --model gpt-4.1 \
  --model-kind chat

Inspect current config

agencode config-show

Check environment health

agencode doctor

Provider Notes

agencode supports OpenAI-compatible providers through:

• --base-url
• --model
• --model-kind
• API key environment variables or keyring storage

If no provider is configured yet, the TUI guides you through onboarding.

Packaging and Install Notes

After pip install agencode, the global command is:

agencode

A compatibility alias may still exist in development environments, but agencode is the intended public command.

MVP Scope

This release is an MVP focused on:

• working TUI experience
• project-local state
• supervisor-managed subagents
• thread-aware history
• skills browsing and install
• keyboard-first workflows

The product is already usable, but the workflow surface will continue to evolve.

Troubleshooting

agencode command not found

Make sure your Python scripts directory is on PATH, or use:

python -m pip install --user agencode

Then restart the shell.

Skills install works but attachment does not

Use /skills to install first, then /agent or /select-skill to attach.

Provider errors

Run:

agencode doctor
agencode config-show

Reset the current session

Inside the TUI, use:

/reset

Development

uv sync
uv run agencode --help
uv run python -m unittest

License

Add your preferred license before broader public distribution if needed.