AGENTS.md in hoangsonww/Forge-Agentic-Coding-CLI runs 1,007 words across 14 headings.
🦄 Forge - a local-first, multi-agent software-engineering runtime that runs Claude Code / Codex-style agentic workflows entirely on your own machine via Ollama, llama.cpp, vLLM, and LM Studio (cloud models optional). Ships 18 sandboxed tools, 6 model providers, and a full REPL + UI dashboard in a single Node CLI - no telemetry, no lock-in.
TypeScriptCovers
9 of the 20 section tags
In the order a file is read inHeadings
14 headings, in the order the file writes them
01AGENTS.md
021. Project identity
032. Commands you'll run
043. Layout
054. Rules
06Must
07Must not
08Good defaults
095. Testing
106. CI quick reference
117. Performance posture
128. Security posture
139. Useful anchors
1410. When uncertain
Commands
10 commands this file writes down
Extracted from the file, verbatimnpm ci --ignore-scripts
npm run build
npm test
npm run typecheck
npm run lint
npm run format
npm run format:check
npm run test:coverage
npm run format && npm run lint && npm run build && npm test
docker/
The file
AGENTS.md
First 160 of 191 lines1# AGENTS.md
2
3Project-wide guidance for any code-writing agent (Codex, OpenAI agent
4runtime, Cursor, Aider, Cline, Continue, …). Claude Code reads this too
5but also reads [CLAUDE.md](CLAUDE.md).
6
7> **Tooling infrastructure.** On top of this file, the repo ships
8> agent-specific wiring so every major coding agent has the same rules,
9> skills, and permissions:
10>
11> - `.claude/` — Claude Code settings, path-scoped rules, skills
12> (`/verify`, `/add-tool`, `/add-provider`, `/add-agent`,
13> `/debug-loop`, `/release-check`), subagents (`code-reviewer`,
14> `test-runner`, `docs-auditor`), and safe/deny permissions.
15> - `.codex/` — Codex `config.toml`, execpolicy `rules/default.rules`,
16> custom agents (`forge_explorer`, `forge_reviewer`,
17> `forge_test_runner`), guardrail hooks, and Codex-native skills.
18> - `.cursor/rules/` — Cursor `*.mdc` rules (always-applied core +
19> path-scoped TypeScript/testing/tools/models/security/UI rules).
20> - `.agents/skills/` — portable skills following the open
21> [agentskills.io](https://agentskills.io/specification) spec. Any
22> compliant agent can read these without vendor-specific wiring.
23>
24> If you update a workflow (e.g. the verify chain), update it in
25> `.agents/skills/verify/SKILL.md` first, then mirror the change into
26> `.claude/skills/verify/SKILL.md` and `.codex/skills/verify/SKILL.md`
27> if they diverge.
28>
29> **Agentic Coding Flywheel.** Forge follows a plan-heavy, bead-driven
30> workflow for any non-trivial change. See [FLYWHEEL.md](FLYWHEEL.md)
31> for the full methodology. In brief:
32>
33> - **Plan space** → `.flywheel/plans/` (iterated markdown plans)
34> - **Bead space** → `.beads/beads.jsonl` (self-contained work units)
35> - **Code space** → `src/` + `test/` (implementation)
36>
37> Skills: `/plan`, `/plan-synthesize`, `/plan-to-beads`,
38> `/polish-beads` (run 4–6×), `/fresh-eyes`, `/dedupe-beads`,
39> `/idea-wizard`, `/deep-review`, `/reality-check`, `/landing`,
40> `/de-slopify`. Subagents: `bead-polisher`, `plan-synthesizer`,
41> `skill-refiner` (Claude); `forge_bead_polisher`,
42> `forge_plan_synthesizer` (Codex). The 8 canonical operators live in
43> `.flywheel/operators/`.
44>
45> **Post-compaction ritual.** When an agent gets confused, send: "Reread
46> AGENTS.md, CLAUDE.md, and FLYWHEEL.md so they're still fresh in your
47> mind." This is the single most common intervention in the
48> methodology.
49
50> Conform to the OpenAI `AGENTS.md` convention: this file is a flat
51> Markdown cheat-sheet that answers the questions "where am I, what
52> can I run, and what shouldn't I break?".
53
54---
55
56## 1. Project identity
57
58Forge is a **TypeScript CLI runtime** for local-first agentic software
59engineering. Node 20+. Ships via npm and a multi-arch Docker image.
60
61- Entry point: `bin/forge.js` → `dist/cli/index.js`
62- Orchestrator: `src/core/orchestrator.ts`
63- Agentic loop: `src/core/loop.ts`
64
65## 2. Commands you'll run
66
67```bash
68npm ci --ignore-scripts
69npm run build # tsc + copy-assets
70npm test # vitest; 249 tests must pass
71npm run typecheck
72npm run lint
73npm run format # writes
74npm run format:check # reads, for CI
75npm run test:coverage
76./bin/forge.js doctor
77```
78
79Always end a change with:
80
81```bash
82npm run format && npm run lint && npm run build && npm test
83```
84
85## 3. Layout
86
87| Path | Purpose |
88|------|---------|
89| `src/cli/` | commander-based CLI, REPL, raw-mode input editor |
90| `src/core/` | orchestrator, agentic loop, mode policy, validation gate |
91| `src/agents/` | planner, architect, executor, reviewer, debugger, memory |
92| `src/models/` | providers (ollama/openai/anthropic/llamacpp/vllm/lmstudio), router, adapter, catalog |
93| `src/tools/` | 18 tools |
94| `src/permissions/` | risk + interactive permission manager |
95| `src/sandbox/` | path-safe fs + command risk classifier |
96| `src/persistence/` | tasks/sessions/conversations/events + SQLite |
97| `src/memory/` | hot/warm/cold/learning |
98| `src/ui/` | HTTP + WS dashboard + static app |
99| `src/mcp/` | MCP bridge |
100| `test/unit/` | vitest unit tests |
101| `docs/` | ARCHITECTURE, INSTALL, SETUP, metrics |
102| `.github/workflows/` | ci, release, nightly |
103| `docker/` | Dockerfile + compose |
104
105## 4. Rules
106
107### Must
108
109- Keep `npm test` at **100%** pass.
110- Respect the state machine in `src/persistence/tasks.ts`.
111- Gate every new tool through `requestPermission`.
112- Classify model ids through `src/models/local-catalog.ts` (don't
113 hand-roll regexes in a new provider).
114- Add a unit test for any new logic in `src/core`, `src/agents`, or
115 `src/tools`.
116
117### Must not
118
119- Bypass the permission system.
120- Introduce network calls in tests — use `vi.mock`.
121- Log credentials. Use `src/security/redact.ts`.
122- Add dependencies without a clear reason.
123- Rename exported APIs without updating every caller + the docs.
124
125### Good defaults
126
127- Prefer `readonly` / immutable data flow.
128- Prefer function modules over classes unless state really needs
129 encapsulation (see the provider classes for the accepted shape).
130- Prefer explicit `Result<T, E>`-style shapes over thrown errors for
131 expected failures. Throw only for programmer errors.
132
133## 5. Testing
134
135Vitest. Patterns to copy:
136
137- Stubbing `callModel`: see `test/unit/executor-loop.test.ts`.
138- Stubbing providers: see `test/unit/adapter.test.ts`.
139- Tempdir + cleanup: see `test/unit/validation-gate.test.ts`.
140
141## 6. CI quick reference
142
1439 parallel jobs on every PR:
144
1451. 🎨 format (prettier --check)
1462. 🧹 lint (eslint)
1473. 🧠 typecheck (tsc --noEmit)
1484. 🧪 test (matrix: ubuntu + macOS × Node 20 + 22)
1495. 📈 coverage
1506. 🏗️ build (full `npm run build`)
1517. 🐳 docker-build (catches Dockerfile drift)
1528. 🔐 audit (npm audit, informational)
1539. 📊 pipeline status (aggregates + fails if any required job failed)
154
155Release (tag `v*`): 6-stage pipeline — gate, artifacts, docker publish to
156GHCR, signed manifest + GH release, npm publish (provenance), status.
157
158## 7. Performance posture
159
160The product runs on personal machines, often alongside Ollama. Keep it
31 more lines are in the file. Read the raw file.
The rest of the repository
hoangsonww/Forge-Agentic-Coding-CLI ships 8 other instruction files
.cursor/rules/testing.mdc.cursor/rules/typescript.mdc.cursor/rules/security.mdc.cursor/rules/models-and-agents.mdc.cursor/rules/tools.mdc.cursor/rules/ui.mdcCLAUDE.md.cursor/rules/forge-core.mdc
A row that is not a link is a file this repository ships that this app did not freeze a sheet for. It is listed because the corpus knows it exists, and it is not linked because there is nothing here to open.
This listing
Whoever runs hoangsonww/Forge-Agentic-Coding-CLI can claim it
This is yours? Claim this config and we will write to you when the measurement moves. The check is one token placed where only you can place it, and there is no account and no password.