Adapted from the black-candle-technologies/forge repository docs.
Internal Black Candle tool for running ACP-backed coding agents through a local Rust harness instead of a vendor-native CLI.
forge-core — shared ACP protocol types, config parsing, and session recordsforged — local daemon that owns session persistence and brokers ACP trafficforge — ratatui client for interactive session control and diff review
- Starting and reconnecting local ACP sessions
- Persisting session metadata in SQLite
- Surfacing agent output, diffs, plan updates, mode changes, and permission prompts
- Handling file and terminal callbacks through
forged
- Restricting the agent to Forge-managed capabilities instead of host Codex or Claude Code configuration
Forge is intentionally an isolation layer:
- Backend agents start with Forge-managed config roots instead of the user's normal home config directories.
- File reads and writes through ACP callbacks are executed by
forged and surfaced back to the UI.
- MCP servers must be explicitly provided through Forge session setup.
- Treat this repository as internal Black Candle infrastructure, not a public SDK or end-user CLI.
forge auto-starts forged if the daemon is not already listening.- File callback activity appears in the UI as explicit read/write system events.
- File write diffs appear in the right-hand diff pane when the backend emits diff content.
- Session provider/model selection is mediated by Forge config options, not direct backend CLI state.
- Globally configured MCP servers attach to new and resumed sessions (MCP count in the top bar,
/mcp lists them).
Forge loads runtime config from ~/.config/forge/config.toml:
[[mcp_servers]]
name = "github"
[[mcp_servers]]
name = "google-calendar"
This milestone supports global MCP server configuration only. Per-project MCP configuration is tracked separately (issue #18).
cargo test # all crates
cargo test -p forge # client only
cargo test -p forged # daemon only
cargo test -p forge-core # protocol/types only
- API keys stay in environment variables and are forwarded only as needed for the selected backend.
- Backend home/config directories can be overridden with
FORGE_BACKEND_HOME for testing.
- Internal use at Black Candle Technologies.