| 1 | # Agent Forge |
| 2 | |
| 3 | **Org:** [AI-Guiders](https://github.com/AI-Guiders) · **License:** MIT · **Stack:** .NET 10, C# 14 |
| 4 | |
| 5 | Agent-first git forge: **repos**, **issues**, **merge requests** — from chat via MCP, not Jira². |
| 6 | |
| 7 | Born from door-to-singularity kanon: open alternative to GitLab friction for human–agent teams. |
| 8 | |
| 9 | **Design:** [ADR index](design/) — 0001–0007 · [0008 IOP](design/FORGE-ADR-0008-process-iop-not-boards.md) · [0009 agent-driven repos](design/FORGE-ADR-0009-agent-driven-vs-human-driven-repos.md) · [0014 plugins](design/FORGE-ADR-0014-microkernel-and-standard-bundle.md) |
| 10 | |
| 11 | > v0.1 — API + bare git repos + MCP. Git push over SSH/HTTP and CI bridge: next milestones. |
| 12 | |
| 13 | ## Quick start (local) |
| 14 | |
| 15 | ```powershell |
| 16 | cd agent-forge |
| 17 | dotnet restore |
| 18 | dotnet run --project src/AgentForge/AgentForge.csproj |
| 19 | ``` |
| 20 | |
| 21 | Open http://127.0.0.1:8770/health |
| 22 | |
| 23 | ### Auth (no eternal PAT in MCP env) |
| 24 | |
| 25 | ```powershell |
| 26 | dotnet run --project cli/AgentForge.Cli -- auth login --host http://127.0.0.1:8770 |
| 27 | # other terminal: forge auth approve <user-code> (FORGE_BOOTSTRAP_TOKEN once) |
| 28 | ``` |
| 29 | |
| 30 | MCP reads `~/.forge/credentials.json` when `FORGE_API_TOKEN` is unset. See [docs/auth.md](docs/auth.md) · [FORGE-ADR-0010](design/FORGE-ADR-0010-auth-login-and-credential-store.md). |
| 31 | |
| 32 | ## Docker |
| 33 | |
| 34 | ```bash |
| 35 | docker compose up --build |
| 36 | ``` |
| 37 | |
| 38 | Set `FORGE_PUBLIC_BASE_URL` and `FORGE_GIT_BASE_URL` for your host when deploying beyond localhost. |
| 39 | |
| 40 | ## Tests |
| 41 | |
| 42 | ```powershell |
| 43 | dotnet test AgentForge.slnx |
| 44 | ``` |
| 45 | |
| 46 | ## Agent onboarding |
| 47 | |
| 48 | Agents read **[docs/skill.md](docs/skill.md)**. |
| 49 | |
| 50 | ## API (v0.2) |
| 51 | |
| 52 | | Endpoint | Description | |
| 53 | |----------|-------------| |
| 54 | | `GET/POST /api/v1/repos` | List / create repos | |
| 55 | | `GET /api/v1/repos/{name}` | Repo + `cloneUrl` | |
| 56 | | `GET/POST /api/v1/repos/{name}/issues` | List (`?q=`) / create (+ `anchors`) | |
| 57 | | `GET/PATCH /api/v1/repos/{name}/issues/{n}` | Get / update issue | |
| 58 | | `POST …/issues/{n}/comments` | Issue thread | |
| 59 | | `POST …/issues/{n}/anchors` | Forge Lens link | |
| 60 | | `GET /api/v1/repos/{name}/lens?file=` | Lens index | |
| 61 | | `GET/POST …/merge-requests` | List / create MR | |
| 62 | | `GET …/merge-requests/{n}` | MR + `mrUrl` | |
| 63 | | `GET …/merge-requests/{n}/ci` | Last CI status | |
| 64 | | `GET /api/v1/capabilities` | Plugin bundle, features, MCP tools ([ADR-0014](design/FORGE-ADR-0014-microkernel-and-standard-bundle.md)) | |
| 65 | | `POST /api/v1/ci/callback` | CI inbound ([ADR-0005](design/FORGE-ADR-0005-ci-webhook-bridge.md)) | |
| 66 | |
| 67 | Responses include `issueUrl`, `mrUrl`, `anchors` (CIDE-compatible). JSON camelCase. |
| 68 | |
| 69 | ## Environment |
| 70 | |
| 71 | | Variable | Default | Description | |
| 72 | |----------|---------|-------------| |
| 73 | | `FORGE_PUBLIC_BASE_URL` | `http://127.0.0.1:8770` | Public API URL | |
| 74 | | `FORGE_DATABASE_PATH` | `./data/forge.witdb` | WitDatabase store (как CIDE / Intercom) | |
| 75 | | `FORGE_REPOS_PATH` | `./data/repos` | Bare git repos root | |
| 76 | | `FORGE_GIT_BASE_URL` | `ssh://git@127.0.0.1` | SSH host config; API `cloneUrl` is scp-style (`git@host:repo.git`) | |
| 77 | | `FORGE_GIT_SSH_PORT` | `22` (`2222` in Compose) | SSH port for git-ssh; use `~/.ssh/config` or `GIT_SSH_COMMAND`, not in `cloneUrl` | |
| 78 | | `FORGE_BASE_URL` | `http://127.0.0.1:8770` | MCP → API base | |
| 79 | | `FORGE_PLUGIN_BUNDLE` | `standard` | Plugin bundle from `forge.plugins.json` (`standard` = view; `minimal` = API only) | |
| 80 | |
| 81 | ## Roadmap |
| 82 | |
| 83 | - [x] API + bare repos (LibGit2Sharp) |
| 84 | - [x] MCP (15+ tools: lifecycle, Lens, CI, provenance, handoff relay) |
| 85 | - [x] Issue/MR lifecycle API + Forge Lens `anchors` + CI callback |
| 86 | - [x] `issueUrl` / `mrUrl` in API responses |
| 87 | - [x] Git SSH transport (Compose git-ssh) — [ADR-0004](design/FORGE-ADR-0004-git-transport-ssh-http.md) |
| 88 | - [x] CI webhook bridge — [ADR-0005](design/FORGE-ADR-0005-ci-webhook-bridge.md) |
| 89 | - [x] Auth tokens + device/OAuth login — [ADR-0006](design/FORGE-ADR-0006-auth-vpn-and-plugins.md), [0010](design/FORGE-ADR-0010-auth-login-and-credential-store.md) |
| 90 | - [x] `drive_mode` agent-driven vs human-driven — [ADR-0009](design/FORGE-ADR-0009-agent-driven-vs-human-driven-repos.md) |
| 91 | - [x] Thin web View-layer (mockup parity, IOP, search, docs) — [ADR-0002](design/FORGE-ADR-0002-mcp-first-web-view-only.md), [0014 View plugin](design/FORGE-ADR-0014-microkernel-and-standard-bundle.md) |
| 92 | - [ ] `forge://` magic links (opt-in) — [ADR-0007](design/FORGE-ADR-0007-forge-magic-link-protocol.md) |
| 93 | - [ ] Static bundled API `/docs` (Doxygen) — [ADR-0002](design/FORGE-ADR-0002-mcp-first-web-view-only.md) |
| 94 | - [ ] CIDE native client + Forge Lens — [ADR-0003](design/FORGE-ADR-0003-forge-lens-cide-code-anchors.md) |
| 95 | - [ ] WitDB NuGet ≥1.0.4 (SQLite `$name` params) — blocked on [WitDatabase#2](https://github.com/dmitrat/WitDatabase/pull/2) |
| 96 | |
| 97 | ## Related |
| 98 | |
| 99 | - [Open Agent Registry](https://github.com/AI-Guiders/open-agent-registry) — agent catalog |
| 100 | - [AI-Guiders handbook](https://github.com/AI-Guiders/handbook) |
| 101 | |