Agent Forge

New issues and PRs from new contributors are auto-closed by default. Maintainers review auto-closed issues daily. See CONTRIBUTING.md.

Agent Forge 是一个极简的终端编程 Agent。内核只提供模型流、会话、工具、事件、生命周期与可版本化公共 API；MCP、Skill、CLI 工具、多 Agent、Goal、Plan 和策略均通过插件接入。将工作流适配给自己，无须修改内核。

默认能力保持最小：Agent Forge 以交互、print/JSON、RPC 和 SDK 方式运行。扩展能力通过 插件、Skills、提示模板与主题安装或实现。

Table of Contents

• Quick Start
• Providers & Models
• Interactive Mode
  • Editor
  • Commands
  • Keyboard Shortcuts
  • Message Queue
• Sessions
  • Branching
  • Compaction
• Settings
• Context Files
• Customization
  • Prompt Templates
  • Skills
  • Extensions
  • Themes
  • Plugins
• Programmatic Usage
• Philosophy
• CLI Reference

Quick Start

npm install -g --ignore-scripts @ai-agent-forge/agent-forge

--ignore-scripts disables dependency lifecycle scripts during install. Agent Forge 的正常安装不依赖安装脚本。

Authenticate with an API key:

export ANTHROPIC_API_KEY=sk-ant-...
agent-forge

Or use your existing subscription:

agent-forge
/login  # Then select provider

然后直接与 Agent Forge 对话。默认工具由可替换的首方插件提供：read、write、edit 与 bash。通过 插件、Skills 或提示模板增加能力。

Platform notes: Windows | Termux (Android) | tmux | Terminal setup | Shell aliases

Providers & Models

Agent Forge 不内置模型目录；模型来自用户 models.json 声明（写法见 docs/design/models-json配置参考.md）。通过订阅（/login）或 API key 认证后，可用 /model 选择模型；在模型选择器中按 Ctrl+S 可保存启动默认值。

Subscriptions:

• Anthropic Claude Pro/Max
• OpenAI ChatGPT Plus/Pro (Codex)
• GitHub Copilot

API keys:

• Anthropic
• Ant Ling
• OpenAI
• Azure OpenAI
• DeepSeek
• NVIDIA NIM
• Google Gemini
• Google Vertex
• Amazon Bedrock
• Mistral
• Groq
• Cerebras
• Cloudflare AI Gateway
• Cloudflare Workers AI
• xAI
• OpenRouter
• Vercel AI Gateway
• ZAI Coding Plan (Global)
• ZAI Coding Plan (China)
• OpenCode Zen
• OpenCode Go
• Hugging Face
• Fireworks
• Together AI
• Baseten
• Kimi For Coding
• MiniMax
• Xiaomi MiMo
• Xiaomi MiMo Token Plan (China)
• Xiaomi MiMo Token Plan (Amsterdam)
• Xiaomi MiMo Token Plan (Singapore)

Agent Forge 也支持 llama.cpp router server。把它作为 OpenAI 兼容自定义 provider 写入 models.json、用 /login llama.cpp 存储 API key，再用 /model 选择模型。参见 docs/llama-cpp.md。

See docs/providers.md for other provider setup instructions.

Custom providers & models: Add providers via ~/.agent-forge/agent/models.json if they speak a supported API (OpenAI, Anthropic, Google). Custom API implementations and OAuth flows existed only through the legacy ExtensionAPI and were removed together with it (D-066); there is currently no plugin-face equivalent. See docs/models.md.

Interactive Mode

The interface from top to bottom:

• Startup header - Shows shortcuts (/hotkeys for all), loaded AGENTS.md files, prompt templates, skills, and themes
• Messages - Your messages, assistant responses, tool calls and results, notifications, and errors
• Editor - Where you type; border color indicates thinking level
• Footer - Working directory, session name, total token/cache usage (↑ input, ↓ output, R cache read, W cache write, CH latest cache hit rate), context usage, current model. Totals include assistant responses, usage reported by tools, and summary generation.

The editor can be temporarily replaced by built-in UI, such as the /settings or /model selectors. Capability plugins cannot host custom TUI components; they interact with the user through the built-in notify, confirm, select, and input prompts.

Editor

| Feature | How | |---------|-----| | File reference | Type @ to fuzzy-search project files | | Path completion | Tab to complete paths | | Multi-line | Shift+Enter (or Ctrl+Enter on Windows Terminal) | | External editor | Ctrl+G opens externalEditor, $VISUAL, $EDITOR, Notepad on Windows, or nano elsewhere | | Clipboard | Ctrl+V to paste an image or text (Alt+V on Windows), or drag images onto terminal | | Bash commands | !command runs and sends output to LLM, !!command runs without sending |

Standard editing keybindings for delete word, undo, etc. See docs/keybindings.md.

Commands

Type / in the editor to trigger commands. Extensions can register custom commands, skills are available as /skill:name, and prompt templates expand via /templatename.

| Command | Description | |---------|-------------| | /login, /logout | Manage provider credentials | | /model | Switch models; Ctrl+S in the picker saves the startup default | | /thinking | Switch thinking level; Ctrl+S in the picker saves the startup default | | /scoped-models | Enable/disable models for model cycling (bindable, no default key) | | /settings | Theme, message delivery, transport, and other preferences | | /resume | Pick from previous sessions | | /new | Start a new session | | /name <name> | Set session display name | | /session | Show session info (file, ID, messages, tokens) | | /tree | Jump to any point in the session and continue from there | | /fork | Create a new session from a previous user message | | /clone | Duplicate the current active branch into a new session | | /compact [prompt] | Manually compact context, optional custom instructions | | /copy | Copy last assistant message to clipboard | | /export [file] | Export session to HTML or JSONL file | | /import <file> | Import and resume a session from a JSONL file | | /reload | Reload keybindings, extensions, skills, prompts, themes, and context files | | /hotkeys | Show all keyboard shortcuts | | /changelog | Display version history | | /quit | 退出 Agent Forge |

Keyboard Shortcuts

See /hotkeys for the full list. Customize via ~/.agent-forge/agent/keybindings.json. See docs/keybindings.md.

Commonly used:

| Key | Action | |-----|--------| | Ctrl+C | Clear editor | | Ctrl+C twice | Quit | | Escape | Cancel/abort | | Escape twice | Open /tree | | Ctrl+O | Collapse/expand tool output | | Ctrl+T | Collapse/expand thinking blocks | | Ctrl+X | Copy the last assistant message; with fullscreen copy-on-select disabled, copy the active text selection |

Model selection, model cycling, and thinking-level cycling are command-only by default (/model, /thinking, /scoped-models); their shipped default keybindings were cleared per the single-entry-point rule and can be re-bound in ~/.agent-forge/agent/keybindings.json (see docs/keybindings.md).

Message Queue

Submit messages while the agent is working:

• Enter queues a steering message, delivered after the current assistant turn finishes executing its tool calls
• /queue <text> queues a follow-up message, delivered only after the agent finishes all work
• Escape aborts and restores queued messages to editor
• /dequeue restores queued messages back to editor

Follow-up queueing and dequeue are command-only by default (no shipped keybindings); bind app.message.followUp / app.message.dequeue in docs/keybindings.md if you want keys.

Configure delivery in settings: steeringMode and followUpMode can be "one-at-a-time" (default, waits for response) or "all" (delivers all queued at once). transport selects provider transport preference ("sse", "websocket", or "auto") for providers that support multiple transports.

Sessions

Sessions are stored as JSONL files with a tree structure. Each entry has an id and parentId, enabling in-place branching without creating new files. See docs/session-format.md for file format.

Management

Sessions auto-save to ~/.agent-forge/agent/sessions/ organized by working directory.

agent-forge -c                  # Continue most recent session
agent-forge -r                  # Browse and select from past sessions
agent-forge --no-session        # Ephemeral mode (don't save)
agent-forge --name "my task"    # Set session display name at startup
agent-forge --session <path|id> # Use specific session file or ID
agent-forge --fork <path|id>    # Fork specific session file or ID into a new session

Use /session in interactive mode to see the current session ID before reusing it with --session <id> or --fork <id>.

Branching

/tree - Navigate the session tree in-place. Select any previous point, continue from there, and switch between branches. All history preserved in a single file.

• Search by typing, fold/unfold and jump between branches with Ctrl+←/Ctrl+→ or Alt+←/Alt+→, page with ←/→
• Filter modes (Ctrl+O): default → no-tools → user-only → labeled-only → all
• Press Ctrl+X to copy the selected message
• Press Shift+L to label entries as bookmarks and Shift+T to toggle label timestamps

/fork - Create a new session file from a previous user message on the active branch. Opens a selector, copies the active path up to that point, and places the selected prompt in the editor for modification.

/clone - Duplicate the current active branch into a new session file at the current position. The new session keeps the full active-path history and opens with an empty editor.

--fork <path|id> - Fork an existing session file or partial session UUID directly from the CLI. This copies the full source session into a new session file in the current project.

Compaction

Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.

Manual: /compact or /compact <custom instructions>

Automatic: Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via /settings or settings.json.

Compaction is lossy. The full history remains in the JSONL file; use /tree to revisit. Customize compaction behavior via extensions. See docs/compaction.md for internals.

Settings

Use /settings to modify common options, or edit JSON files directly:

| Location | Scope | |----------|-------| | ~/.agent-forge/agent/settings.json | Global (all projects) | | .agent-forge/settings.json | Project (overrides global) |

See docs/settings.md for all options.

联网行为

Agent Forge 不配置默认版本检查上游。只有用户显式设置 AGENT_FORGE_VERSION_CHECK_URL 时，才会查询该地址；用 AGENT_FORGE_SKIP_VERSION_CHECK=1 或 AGENT_FORGE_OFFLINE=1 禁用该可选查询。

Context Files

Agent Forge loads AGENTS.md (or CLAUDE.md) at startup from:

• ~/.agent-forge/agent/AGENTS.md (global)
• Parent directories (walking up from cwd)
• Current directory

If a directory contains AGENTS.override.md, Agent Forge loads it instead of AGENTS.md or CLAUDE.md from that directory. Context files from other directories are still concatenated.

Use for project instructions (AGENTS.md/CLAUDE.md), conventions, common commands. All matching files are concatenated.

Disable context file loading with --no-context-files (or -nc).

System Prompt

Replace the default system prompt with .agent-forge/SYSTEM.md (project) or ~/.agent-forge/agent/SYSTEM.md (global). Append without replacing via APPEND_SYSTEM.md.

Customization

Prompt Templates

Reusable prompts as Markdown files. Type /name to expand.

<!-- ~/.agent-forge/agent/prompts/review.md -->
Review this code for bugs, security issues, and performance problems.
Focus on: {{focus}}

Place in ~/.agent-forge/agent/prompts/, .agent-forge/prompts/, or a plugin package to share with others. See docs/prompt-templates.md.

Skills

On-demand capability packages following the Agent Skills standard. Invoke via /skill:name or let the agent load them automatically.

<!-- ~/.agent-forge/agent/skills/my-skill/SKILL.md -->
# My Skill
Use this skill when the user asks about X.

## Steps
1. Do this
2. Then that

Place in ~/.agent-forge/agent/skills/, ~/.agents/skills/, .agent-forge/skills/, or .agents/skills/ (from cwd up through parent directories) or a plugin package to share with others. See docs/skills.md.

Themes

Built-in: dark, light. Themes hot-reload: modify the active theme file and Agent Forge immediately applies changes.

Place in ~/.agent-forge/agent/themes/, .agent-forge/themes/, or a plugin package to share with others. See docs/themes.md.

Plugins

Plugins bundle optional capabilities such as MCP bridges, CLI tools, Skills, Goal/Plan workflows and multi-Agent orchestration. MCP servers themselves are configured in mcp.json and materialized as generated plugins; see docs/mcp.md. A plugin is self-describing through plugin.json and can be installed, disabled, replaced or removed without modifying the core.

Execution model: Plugins run with the process capabilities available in readonly or full-control. The core does not provide approval or trust policy; install a policy plugin when that behavior is required.

Create a plugin directory under ~/.agent-forge/agent/plugins/ or .agent-forge/plugins/:

{
  "id": "example.my-plugin",
  "version": "0.1.0",
  "apiVersion": "1-draft",
  "entry": "./index.ts",
  "requiredCapabilities": ["tools"]
}

Capability plugin manifests are validated before loading. See examples/extensions/ for MCP, CLI bridge, Goal/Plan and multi-Agent templates. Package resource manifests are declared under the agent-forge key of a package.json; capability plugins via plugin.json are the recommended extension path.

See docs/packages.md.

Programmatic Usage

SDK

import { createStableAgentSession, ModelRuntime, SessionManager } from "@agent-forge/agent-forge";

const modelRuntime = await ModelRuntime.create();
const { facade } = await createStableAgentSession({
  sessionManager: SessionManager.inMemory(),
  modelRuntime,
});

await facade.prompt("What files are in the current directory?");

For advanced multi-session runtime replacement, use createStableAgentSessionRuntime() and CodingAgentRuntimeFacadeV1. The result has no raw runtime or session on the surface: runtimeFacade.getSessionFacade() returns the current session's CodingAgentFacadeV1 and follows every replacement, so callers re-read instead of caching it. The legacy createAgentSessionRuntime() stays available as the lower-level entry.

See docs/sdk.md and examples/sdk/.

RPC Mode

For non-Node.js integrations, use RPC mode over stdin/stdout:

agent-forge --mode rpc

RPC mode uses strict LF-delimited JSONL framing. Clients must split records on \n only. Do not use generic line readers like Node readline, which also split on Unicode separators inside JSON payloads.

See docs/rpc.md for the protocol.

Remote Server (experimental)

Serve the coding-agent session runtime over TCP from the CLI:

agent-forge --serve 8787

实验功能，仅适合单用户本机信任环境：监听默认绑定 loopback（127.0.0.1），没有默认鉴权，本机任何进程都能驱动该 agent。可用 --serve-workspace-root <dir>（可重复）把远程 create 限制在指定目录树内；省略时客户端可提交任意 cwd。

持久化 journal 写入 <agentDir>/remote-server-journal.jsonl（默认在 ~/.agent-forge/agent/ 下），不落在进程 cwd。未装配 durable 时 operation 面返回 durable_unavailable；完整的 durable 与 executor 装配走 programmatic 入口 startCodingAgentRemoteServer()。

用 @agent-forge/client 连接：

import { PiClient } from "@agent-forge/client";
import { createTcpTransportFactory } from "@agent-forge/client/tcp";

const client = new PiClient({
  transportFactory: createTcpTransportFactory({ host: "127.0.0.1", port: 8787 }),
});
await client.connect();

const session = await client.createSession({ cwd: process.cwd() }); // or attachSession(existingId)
session.subscribe((snapshot) => console.log(`revision ${snapshot.revision}`));
await session.prompt("What files are in the current directory?");

完整可运行示例（临时端口、快照订阅与优雅关闭）见 examples/remote-client.ts；客户端 transport、requestTimeoutMs 与 SessionLease operation 方法的完整说明见 packages/client/README.md。

prompt、attach 等等待完整 agent turn 的请求是长运行请求：客户端默认 requestTimeoutMs 为 5 分钟（300000 ms），这是防挂死兜底而非长任务上限；更长任务可调大该值，设 0 完全禁用超时。

Philosophy

Agent Forge 保持可扩展而不规定工作流。其它工具内置的能力都应通过 插件、Skills 或外部工具接入；这样内核保持最小，工作流由用户塑造。

No core MCP. 通过 mcp.json 配置接入（项目级 .agent-forge/mcp.json 与用户级 agent dir，stdio 与 remote HTTP 两种 server 形态）；每个 server 在会话启动时物化为生成的 capability 插件。见 docs/mcp.md。

No core multi-Agent workflow. 通过插件实现编排与生命周期策略。

No core approval policy. 如有需要，通过策略插件实现确认、审计或隔离。

No core Plan mode. 通过 Goal/Plan 插件实现。

No built-in to-dos. They confuse models. Use a TODO.md file, or build your own with extensions.

No background bash. Use tmux. Full observability, direct interaction.

完整原则见仓库的 核心架构宪法。

CLI Reference

agent-forge [options] [--] [@files...] [messages...]

Package Commands

agent-forge install <source> [-l]     # Install package, -l for project-local
agent-forge remove <source> [-l]      # Remove package
agent-forge uninstall <source> [-l]   # Alias for remove
agent-forge update [source|self|agent-forge] # Update Agent Forge or one package source
agent-forge update --all              # Update Agent Forge and packages
agent-forge update --packages        # Update packages only
agent-forge update --self             # Update Agent Forge only
agent-forge update --self --force     # Reinstall Agent Forge even if current
agent-forge update --package <src>   # Update one package
agent-forge list                      # List installed packages
agent-forge config                    # Enable/disable package resources

Modes

| Flag | Description | |------|-------------| | (default) | Interactive mode | | -p, --print | Print response and exit | | --mode json | Output all events as JSON lines (see docs/json.md) | | --mode rpc | RPC mode for process integration (see docs/rpc.md) | | --export <in> [out] | Export session to HTML |

In print mode, Agent Forge also reads piped stdin and merges it into the initial prompt:

cat README.md | agent-forge -p "Summarize this text"

Model Options

| Option | Description | |--------|-------------| | --provider <name> | Provider (anthropic, openai, google, etc.) | | --model <pattern> | Model pattern or ID (supports provider/id and optional :<thinking>) | | --api-key <key> | API key (overrides env vars) | | --thinking <level> | off, minimal, low, medium, high, xhigh, max | | --models <patterns> | Comma-separated patterns for model cycling (bindable, no default key) | | --list-models [search] | List available models |

Session Options

| Option | Description | |--------|-------------| | -c, --continue | Continue most recent session | | -r, --resume | Browse and select session | | --session <path\|id> | Use specific session file or partial UUID | | --fork <path\|id> | Fork specific session file or partial UUID into a new session | | --session-dir <dir> | Custom session storage directory | | --no-session | Ephemeral mode (don't save) | | --name <name>, -n <name> | Set session display name at startup |

Tool Options

| Option | Description | |--------|-------------| | --tools <list>, -t <list> | Allowlist specific tool names across built-in, plugin, and custom tools | | --exclude-tools <list>, -xt <list> | Disable specific tool names across built-in, plugin, and custom tools | | --no-builtin-tools, -nbt | Disable built-in tools by default but keep plugin/custom tools enabled | | --no-tools, -nt | Disable all tools by default |

Available built-in tools: read, bash, powershell (Windows), edit, write, grep, find, ls

Resource Options

| Option | Description | |--------|-------------| | --skill <path> | Load skill (repeatable) | | --no-skills | Disable skill discovery | | --prompt-template <path> | Load prompt template (repeatable) | | --no-prompt-templates | Disable prompt template discovery | | --theme <path> | Load theme (repeatable) | | --no-themes | Disable theme discovery | | --no-context-files, -nc | Disable AGENTS.md and CLAUDE.md context file discovery |

Combine --no-* with explicit flags to load exactly what you need, ignoring settings.json (e.g., --no-skills --no-prompt-templates).

Other Options

| Option | Description | |--------|-------------| | --system-prompt <text> | Replace default prompt (context files and skills still appended) | | --append-system-prompt <text> | Append to system prompt | | --tui-mode <mode> | TUI mode: regular (default) or experimental fullscreen | | --use-theme <name[/name]> | Set the initial interactive theme for this run without changing settings | | --verbose | Force verbose startup | | -- | Stop option parsing; remaining arguments are prompts or @file inputs | | -h, --help | Show help | | -v, --version | Show version |

File Arguments

Prefix files with @ to include in the message:

agent-forge @prompt.md "Answer this"
agent-forge -p @screenshot.png "What's in this image?"
agent-forge @code.ts @test.ts "Review these files"

Examples

# Interactive with initial prompt
agent-forge "List all .ts files in src/"

# Non-interactive
agent-forge -p "Summarize this codebase"

# Prompt beginning with a dash
agent-forge -p -- "- Summarize these points"

# Non-interactive with piped stdin
cat README.md | agent-forge -p "Summarize this text"

# Named one-shot session
agent-forge --name "release audit" -p "Audit this repository"

# Different model
agent-forge --provider openai --model gpt-4o "Help me refactor"

# Model with provider prefix (no --provider needed)
agent-forge --model openai/gpt-4o "Help me refactor"

# Model with thinking level shorthand
agent-forge --model sonnet:high "Solve this complex problem"

# Limit model cycling
agent-forge --models "claude-*,gpt-4o"

# Read-only mode
agent-forge --tools read,grep,find,ls -p "Review the code"

# Disable one extension or built-in tool while keeping the rest available
agent-forge --exclude-tools ask_question

# High thinking level
agent-forge --thinking high "Solve this complex problem"

Environment Variables

| Variable | Description | |----------|-------------| | AI_AGENT | CLI 与 RPC 入口设为 agent-forge，供通用工具识别启动它的 Agent | | AGENT_FORGE | CLI 与 RPC 入口设为 true，供子进程识别 Agent Forge 运行环境 | | AGENT_FORGE_DIR | Override config directory (default: ~/.agent-forge/agent) | | AGENT_FORGE_SESSION_DIR | Override session storage directory (overridden by --session-dir) | | AGENT_FORGE_PACKAGE_DIR | Override package directory (useful for Nix/Guix where store paths tokenize poorly) | | AGENT_FORGE_OFFLINE | 禁用可选联网操作，包括用户配置的版本检查地址 | | AGENT_FORGE_SKIP_VERSION_CHECK | 禁用用户配置的版本检查地址查询 | | AGENT_FORGE_CACHE_RETENTION | Set to long for extended prompt cache (Anthropic: 1h, OpenAI: 24h) | | VISUAL, EDITOR | Fallback external editor for Ctrl+G when externalEditor is unset; defaults to Notepad on Windows and nano elsewhere |

Commands run by the LLM-callable bash and powershell tools also receive current session metadata:

| Variable | Description | |----------|-------------| | AGENT_FORGE_SESSION_ID | Current session ID | | AGENT_FORGE_SESSION_FILE | Absolute session JSONL path; unset for ephemeral sessions | | AGENT_FORGE_PROVIDER | Currently selected model provider | | AGENT_FORGE_MODEL | Currently selected model ID | | AGENT_FORGE_REASONING_LEVEL | Current effective reasoning level |

These values are resolved when each command starts. See Environment Variables for semantics, examples, and custom-tool opt-out.

Contributing & Development

See CONTRIBUTING.md for guidelines and docs/development.md for setup, forking, and debugging.

License

MIT

See Also

• @agent-forge/ai: Core LLM toolkit
• @agent-forge/agent-core: Agent framework
• @agent-forge/tui: Terminal UI components