Metadata-Version: 2.4
Name: agencode
Version: 0.1.1
Summary: AgenCLI: a multi-agent terminal workspace built in Python.
Requires-Python: >=3.12
Requires-Dist: deepagents
Requires-Dist: httpx>=0.28.1
Requires-Dist: keyring>=25.6.0
Requires-Dist: langchain
Requires-Dist: langchain-mcp-adapters
Requires-Dist: langchain-openai
Requires-Dist: langgraph
Requires-Dist: langgraph-checkpoint-sqlite
Requires-Dist: rich>=14.1.0
Requires-Dist: textual>=6.2.1
Requires-Dist: tomli-w>=1.2.0
Requires-Dist: typer>=0.19.2
Description-Content-Type: text/markdown

# 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

```bash
pip install agencode
```

Then run:

```bash
agencode --help
agencode tui
```

## First Run

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

```bash
cd /path/to/project
agencode tui
```

On first run, `agencode` creates:

```text
/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

```bash
cd /path/to/project
agencode tui
```

### Open a specific workspace

```bash
agencode tui --workspace /path/to/project
```

### Configure an OpenAI-compatible provider

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

### Inspect current config

```bash
agencode config-show
```

### Check environment health

```bash
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:

```bash
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:

```bash
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:

```bash
agencode doctor
agencode config-show
```

### Reset the current session

Inside the TUI, use:

```text
/reset
```

## Development

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

## License

Add your preferred license before broader public distribution if needed.
