Orchestrate a team of agents. Ship verified code.
ForgeAI is the orchestration layer for Claude Code: five specialist agents under one conductor, guardrails that gate every ship, and a persistent memory layer so the team never starts from zero.
What ForgeAI actually is.
ForgeAI turns Claude Code into a coordinated team. The conductor doesn't code first: it dispatches an Architect, then a Planner, then parallel Executors, then a Tester, then a Verifier. Nothing is "ready" until the Verifier is green.
Underneath, every session writes to persistent memory in Postgres. Decisions, plans, blockers, files touched, tasks done. The next session, on any repo, on any day, loads exactly the slice it needs. The team never starts from zero.
verify-ship.sh diffs BE routes against FE URLs and smoke-tests every endpoint. Auto-runs on post-deploy hooks.claude -p as a subprocess. Your Claude Code auth. No OpenAI, no Anthropic API, no embeddings provider.The team: five agents, one brain.
Claude Code's subagent system gets used as a team of specialists. Each has a job; none crosses over. The main agent is the conductor.
How the conductor uses them
For any non-trivial feature, the main agent does not code first. It calls the Architect for the design, then the Planner to sequence steps, then dispatches Executors in parallel as background tasks, then runs Tester specs, then ends with the Verifier. Only when Verifier is green does the agent declare "ready."
Why parallel beats serial
Executors run in parallel because they touch different files / different repos. The conductor dispatches them with run_in_background: true, gets notified when each finishes, and aggregates. A serial chain of 4 executors at 8 min each takes 32 min; parallel takes 8.
Loop until done.
When something fails, the conductor retries, diagnoses, and loops. It does not ping the founder for micro-decisions.
--no-verify or sleep-loops.Guardrails: the rules that always apply.
Hard rules baked into the agent's instructions and the verifier. The agent literally cannot violate these without explicit override.
bin/verify-ship.sh. It diffs BE routes vs FE URLs and smoke-tests every FE-called endpoint. Any FAIL line means it's not ready./workspace/sattvah-tests is the single source of "what works in prod." Every new route, endpoint, or behavior gets a spec in the same diff.gh, git push, clone, or PR. The wrong account silently writes to the wrong org.run_in_background: true. Multi-agent parallel preferred over serial. Never sit on long synchronous tool calls.project_<topic>.md snapshot during any non-trivial session. Update on every commit, branch cut, decision, or pause signal. Never wait for session end : sessions die without warning.cognito-idp update-user-pool REPLACES the full config; partial updates wipe LambdaConfig and every unset field. Always describe-user-pool first, merge by hand, re-apply full config.rm -rf /, force-push to main, DROP TABLE, etc.) are blocked at the Claude Code PreToolUse hook by forge guard. Exit 2 = block. The agent literally cannot fire them./Users/mano/Desktop/workspace/sattvah-api. hissme-api directory is legacy and forbidden territory. Never read, edit, or push to it.The foundation: persistent memory.
Orchestration only works if the team remembers what happened. ForgeAI watches every Claude Code session on your machine, extracts load-bearing memory, stores it in Postgres, and auto-injects the relevant slice back into every new session.
The result: every agent in the team resumes correctly. Across days. Across machines. Across projects. You stop being the bridge that carries context from yesterday into today.
The whole thing rides on top of Claude Code's hook system. No daemon, no background worker, no separate service. The forge binary is invoked at session boundaries, does its job in a few seconds, and exits.
Why no embeddings
- No API calls allowed. OpenAI embeddings require a network call to an external service. Hard rule, no exceptions.
- Postgres FTS is enough for chat-summary text. The extractor writes specific nouns ("Razorpay", "Sonnet", "₹1500"), and
ts_rankretrieves them with high precision. You lose semantic generalization but you keep precise keyword recall.
If semantic precision ever matters, the architecture supports plugging in a local embedding model (Ollama with nomic-embed-text) later. The schema needs one extra column. Not doing it now.
Two axes: project and repo.
Every memory carries two independent tags. Understanding this prevents 99% of cross-contamination.
| Tag | Source | Example |
|---|---|---|
| repo_slug | Auto-derived from pwd at session time (Claude's own folder slug) |
-Users-mano-Desktop-workspace-sattvah-api |
| project_slug | The strategic-project bucket: FORGE_PROJECT env or forge project use |
forge, wells, forge-ai |
A repo is "where the code lives on disk." A project is "what strategic thing this repo belongs to." One project can group N repos; one repo belongs to one project at a time.
Create a project
forge project new forge --name "Coaches + Subscribers"
forge project new wells --name "Wells: find help"
forge project new forge-ai --name "ForgeAI: persistent memory"
Slugs are forever (used as foreign keys). Display name and description can change later via the DB.
Attach a repo (records the absolute path)
cd ~/Desktop/workspace/sattvah-api
forge project use forge # make 'forge' active for this shell
forge project attach # links cwd + SAVES the absolute path
After attach, forge p forge works from any directory because the path is recorded in forge_project_repos.repo_path.
Switch projects, three ways
export FORGE_PROJECT=wells
forge project use wells
forge p wells
The env var wins if both are set. To unset: unset FORGE_PROJECT or forge project clear.
Load memory from sessions elsewhere.
If a Claude Code session ran before forge was installed, or in a shell with no FORGE_PROJECT, the transcripts are still on disk. You can ingest them after the fact and tag them correctly.
Ingest old transcripts
# Backfill: scan transcripts from the last 60 days
forge ingest
# Override lookback window
forge ingest --days 180
# Re-extract just the currently-active session
forge ingest-current
Ingest is idempotent: it skips sessions already in the DB (keyed by session_id). Safe to run repeatedly.
Fix the tags with forge retag
After ingest, memories carry whichever FORGE_PROJECT was set when each session originally ran (or NULL if none). To fix:
# I know session de83... belonged to 'forge'
forge retag --session de83f496-1df9-4e66-8052-4e8d900648eb --to forge
# Everything in this repo over the last 60 days belongs to 'forge'
forge retag --repo -Users-mano-Desktop-workspace-sattvah-api --to forge
# Sweep up everything still untagged into a default bucket
forge retag --untagged --to forge
# Bulk move every memory from one project to another
forge retag --from forge --to forge-ai
# ALWAYS preview big moves first
forge retag --from forge --to forge-ai --dry-run
# Strip the project tag entirely
forge retag --from forge --to none
Filters combine, so --from forge --repo my-repo --to forge-ai retags only the intersection. Destination project must already exist (forge project new <slug>) unless you're retagging --to none.
Three rules to keep buckets clean.
Cross-contamination ("I'm working on wells but I'm seeing forge-ai decisions") happens when sessions write to the wrong bucket. These three rules prevent it.
FORGE_PROJECT once when you open the terminal (or let forge p <slug> set it for you). Don't flip mid-session. The Stop hook reads FORGE_PROJECT at every turn, so if you change it, new turns land in the new bucket while old turns stay in the old one. Messy.forge p <slug> for new sessionsclaude. Three sources of error collapsed into one command. Use this 99% of the time. Plain claude is the exception.forge recall-context, which reads pwd for the repo and $FORGE_PROJECT for the project, then injects memories matching either. The project memories span all attached repos; the repo memories cover untagged work in this folder.Verify integrity at a glance
# What gets injected at session start in this shell?
forge recall-context
# What's in a specific project, across all repos?
forge timeline --project forge
# Verify a session landed in the right bucket
forge timeline --session <session-id>
# All projects + memory counts + attached repos
forge project list
# DB connection, claude on PATH, active project
forge status
forge retag --from wells --repo <wrong-repo> --to forge moves the misplaced memories in one shot. Always run with --dry-run first.
Prerequisites.
Install these once per machine. The bootstrap script fails loudly if any are missing.
| Requirement | Why | Install |
|---|---|---|
| Docker Desktop running |
Hosts Postgres locally via docker-compose. Forge will not start without it. |
brew install --cask docker, then launch Docker.app and verify with docker ps. |
| Go 1.22+ | Builds the forge binary from source. |
brew install go |
| Claude Code CLI required |
Extraction calls claude -p as a subprocess. The whole point: no API keys, your existing subscription. |
Install from claude.ai/code. Confirm with which claude. |
| psql client optional |
Manual DB inspection. Forge does not need it. | brew install libpq && brew link --force libpq |
| ~/bin on PATH | So forge runs from any cwd. |
Add export PATH="$HOME/bin:$PATH" to ~/.zshrc. |
localhost:5432 via the named volume forge-pgdata. Data survives docker compose stop; it's lost only on docker compose down -v. To migrate to RDS later, only DATABASE_URL changes : no code changes.
claude -p, which uses your existing Claude Code auth.
Five minutes to running.
Clone, bootstrap, ingest, install the hooks, drop in the skills. Done.
# 1. Clone the repo
git clone git@github.com:Sattvah-labs/sattvah-forge-ai.git
cd sattvah-forge-ai
# 2. Bootstrap (Docker up, schema applied, binary built)
bash scripts/bootstrap.sh
# 3. Backfill from your last 60 days of sessions
./forge ingest
# 4. Try it
./forge timeline
./forge recall "what did we decide about pricing"
# 5. Wire into Claude Code (one-time per machine)
./forge install-hook
# 6. Drop the skills in
cp -r claude/skills/* ~/.claude/skills/
From this point on, every new Claude Code session opens with all relevant memory already injected.
Cannot connect to the Docker daemon
Open Docker Desktop, wait for the whale icon to settle, then re-run bash scripts/bootstrap.sh.
One command to switch context.
After the one-time setup, you only ever need forge p <slug>.
forge p forge-ai # orchestration / memory layer
forge p wells # consumer find-help product
forge p forge # coaches and subscribers product
What it does, in one line
- Sets
FORGE_PROJECT=<slug>for the session cds to the project's most-recently-attached repo- Auto-attaches the current dir to the project if no path is saved yet
execsclaude --dangerously-skip-permissions(replaces the shell)
First launch, choosing the repo
forge p wells --here # current cwd becomes wells's repo
forge p wells --in ~/code/wells # explicit dir
forge p new-thing --new --here # creates project AND attaches cwd
After that, forge p wells from anywhere works, it remembers the path. When you exit claude, you're back in your original shell, original cwd. The Stop hook keeps memory growing per-turn while you chat.
Flags
| Flag | Effect |
|---|---|
--here | Use current cwd as the repo (overrides saved path) |
--in DIR | Use the given dir as the repo |
--new | Create the project if it doesn't exist |
--no-skip | Don't pass --dangerously-skip-permissions |
--bin PATH | Override the claude binary location |
System architecture.
Four moving parts, each replaceable in isolation.
Repo layout
sattvah-forge-ai/
├── README.md
├── docs/
│ ├── ARCHITECTURE.md
│ ├── HOOKS.md
│ ├── SKILLS.md
│ ├── GUARDRAILS.md
│ ├── MULTI_PROJECT.md
│ └── site/ # this site, deployed to nine.sattvah.ai
├── claude/
│ ├── skills/ # drop-in Claude Code skills
│ └── hooks/ # example hook JSON snippets
├── cmd/forge/ # the CLI entrypoint
│ ├── main.go # subcommand dispatcher
│ ├── launch.go # forge p <slug>
│ ├── project.go # forge project ...
│ ├── retag.go # forge retag
│ └── ingest.go # forge ingest / ingest-current
├── internal/
│ ├── parser/ # reads .jsonl transcripts
│ ├── extractor/ # chunked, zero-loss extraction
│ ├── llm/ # claude -p subprocess wrapper
│ ├── store/ # Postgres + tsvector
│ ├── config/ # .env loader
│ └── model/ # shared types
├── migrations/
│ └── 001_init.sql
├── scripts/bootstrap.sh
└── docker-compose.yml # postgres:16-alpine
Hooks: where forge plugs into Claude.
Four hook types, all optional, all idempotent. forge install-hook wires SessionStart + Stop automatically.
forge recall-context, which detects the repo from cwd and injects every relevant memory into the system prompt.forge ingest-current, which re-extracts the active session so memory grows live, no waiting for nightly cron.forge recall "<prompt>" for top-K full-text hits. Useful when you want query-aware injection per turn.forge guard --tool Bash, which can block (exit 2) or allow (exit 0). Pattern-based dangerous-op blocker.Example settings.local.json after install-hook
{
"hooks": {
"SessionStart": [
{
"command": "forge recall-context",
"timeout": 30
}
],
"Stop": [
{
"command": "forge ingest-current",
"timeout": 900
}
],
"PreToolUse": [
{
"matcher": "Bash",
"command": "forge guard --tool Bash"
}
]
}
}
Skills: forge as slash commands.
Drop-in Claude Code skills that wrap forge subcommands. The agent invokes them by name when relevant.
--days, --kind, --project.Skills live in claude/skills/ in this repo. Drop them in with cp -r claude/skills/* ~/.claude/skills/. They're plain markdown with frontmatter, no code to compile.
Multi-repo, multi-terminal.
N terminals open, each cd'd into a different repo, each running its own Claude Code session. Forge handles this naturally.
- Each session's SessionStart hook fires
forge recall-context - The hook reads
pwd, derives the Claude Code project-folder slug (the repo slug), and injects only that repo's memory (plus a cross-repo decision feed) - All sessions write into the same Postgres. The DB handles concurrent reads + writes correctly
When several repos belong to one strategic initiative (a launch, a feature, a customer), group them with forge project. Activating a project makes recall span every attached repo at once.
DATABASE_URL at a remote Postgres (RDS, Neon, Supabase). Every machine syncs through that one DB. No code change required.
Command reference.
Every forge subcommand, one line each.
| Command | What it does |
|---|---|
forge p <slug> | The launcher. Sets FORGE_PROJECT, cds to repo, execs claude --dangerously-skip-permissions. Flags: --here, --in DIR, --new, --no-skip, --bin. |
forge init-db | Apply schema. Idempotent. |
forge ingest | Scan transcripts, run claude -p to extract, store. Skips already-processed sessions. |
forge ingest --days 30 | Lookback override. |
forge ingest-current | Re-extract the active session. Use as a Stop hook. |
forge recall "<query>" | Postgres full-text search. Markdown out. |
forge recall "<query>" --repo SLUG | Restrict to one repo. |
forge recall-context | Session-start hook entrypoint. Auto-detects cwd to repo. Unlimited window by default. |
forge timeline | Recent decisions + tasks + blockers, newest first. |
forge timeline --days 30 --kind decision | Filtered timeline. |
forge project new <slug> | Create a strategic-project bucket. |
forge project use <slug> | Activate a project for the current shell. |
forge project list | Show all projects with attached repos. |
forge project show <slug> | One project: repos, memory count, created date. |
forge project attach [--repo SLUG] | Link cwd (or given repo) to active project. Records absolute path so forge p can reuse it. |
forge project detach [--repo SLUG] | Unlink a repo from a project. |
forge project archive <slug> | Mark project archived (memories stay). |
forge retag --to <project> [filter] | Move memories between buckets. Filters: --session, --from, --repo, --untagged. Add --dry-run to preview. |
forge status | Config + DB state. Verifies claude is on PATH. |
forge install-hook | Auto-merges SessionStart + Stop hooks into ~/.claude/settings.local.json. Idempotent. |
forge install-cron | Prints macOS launchd plist for the nightly safety net. |
forge workstream and forge ws still work as aliases for forge project.
Troubleshooting.
"Cannot connect to the Docker daemon"
Docker Desktop isn't running. Open it, wait for the whale icon to settle, then re-run bash scripts/bootstrap.sh.
"forge: command not found"
Binary isn't on PATH. Either run ./forge from the repo, or install to ~/bin/forge and ensure ~/bin is in PATH.
Ingest hangs at chunk N/M
Per-chunk claude -p timeout is 15 min (v0.8+). If you hit it, the chunk is probably massive (a single multi-MB turn). Check the transcript at ~/.claude/projects/<slug>/<session>.jsonl for outlier turns.
Memories landed in the wrong project
Use forge retag with the appropriate filter. Always preview with --dry-run first.
Recall returns empty
Check three things: (1) forge status shows DB connected, (2) forge project list shows the expected memory count for the active project, (3) FTS query syntax: ts_query doesn't like raw quotes or stop-words.
Two repos got attached to the same project by mistake
forge project detach --project <p> --repo <wrong-slug> then re-attach from the correct cwd.
What ForgeAI is not.
Worth being explicit about. Avoids scope creep arguments later.
- Not a task tracker. Memories describe what happened. They do not schedule what is next.
- Not an agent runtime. Claude Code already runs the agents. Forge is the orchestration and memory layer underneath.
- Not a UI. One CLI. Text output. Build any UI by reading
forge_memories. - Not a PRD or design-doc store. Those live in docs, Linear, or your wiki.
- Not a vector DB. Postgres full-text search by design. Embeddings can be added later, but only locally (Ollama), never via API.
The data is yours. The schema is stable. Everything else is wrapping.