nine.sattvah.ai : ForgeAI developer portal

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.

5 Specialist agents
11 Baked-in guardrails
1 gate Verifier before ship
0 API calls or keys

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.

Five-agent team
Architect, Planner, Executors (parallel), Tester, Verifier. Each has a job. The conductor never crosses lanes.
Verifier-gated ships
No feature is "ready" until verify-ship.sh diffs BE routes against FE URLs and smoke-tests every endpoint. Auto-runs on post-deploy hooks.
Parallel by default
Independent executors run as background agents. 4 jobs at 8 min serial is 32 min. Parallel is 8.
Guardrails baked in
PreToolUse pattern blocker, no-deploy without sign-off, no-em-dash, GitHub-account check. The agent literally cannot violate them.
Persistent memory underneath
Every transcript chunked, every decision stored in Postgres. New sessions load every relevant memory at start. Zero context loss.
Zero API spend
Extraction runs through 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.

A
Architect
Designs the system. Picks data shapes, file boundaries, trade-offs.
P
Planner
Turns goal into ordered steps. Identifies critical files. Sequences work.
E
Executor
Background workers that edit code, run builds, commit branches in parallel.
T
Tester
Writes and runs Playwright specs for every new route or behavior.
V
Verifier
Diffs BE routes vs FE URLs, smoke-tests every endpoint before "ready."

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."

Conductor Architect design Planner sequence Executor x N parallel Tester playwright Verifier verify-ship Ready to ship only after Verifier = GREEN
Conductor fans out to 5 specialists. Verifier is the only gate to "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.

Never block the founder on long synchronous tool calls. Big work goes to background agents. The conductor returns control to the user immediately and merges results as agents complete.

Loop until done.

When something fails, the conductor retries, diagnoses, and loops. It does not ping the founder for micro-decisions.

1
Try
Execute the action. Capture stdout, stderr, exit code.
2
Diagnose
On failure, read the error. Identify root cause. Don't paper over with --no-verify or sleep-loops.
3
Fix
Apply the smallest change that addresses the root cause. Re-run the action.
4
Loop, up to N attempts
Default: 3 attempts per failure mode. After that, escalate to founder with concrete diagnostic data, not vague "I tried."
5
Interrupt only for real forks
Genuine product decisions (architecture, pricing, scope) or destructive-action permission (force-push, drop table, delete branch). Never for micro-choices the agent should make.

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.

Verify before declaring "ready"
Any feature, route change, FE API helper change, or deploy MUST pass 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.
Hook: post-deploy bash hook runs verifier automatically
No production deploy without explicit sign-off
Founder controls when changes land on sattvah.ai, api.sattvah.ai, etc. Agent stops at local commit and asks before any deploy. No exceptions, even for "trivial" fixes.
Memory rule: feedback_no_deploy_without_signoff
Every new feature ships with a sattvah-tests automation
Playwright suite at /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.
Memory rule: feedback_sattvah_tests_suite
No em-dashes or en-dashes
Hard ban on the long horizontal punctuation marks anywhere: chat, code comments, Jira, commits, PR bodies, files. Use hyphen, colon, comma, or sentence break.
Memory rule: feedback_no_dashes
Confirm GitHub account before any GitHub action
Two identities live on this machine: mano-amura (for amura-ai) and sattvahh (for Sattvah-labs). Always ask which one before gh, git push, clone, or PR. The wrong account silently writes to the wrong org.
Memory rule: feedback_github_account_check
Run bigger tasks in background, never block
Non-trivial work goes to background Agents with run_in_background: true. Multi-agent parallel preferred over serial. Never sit on long synchronous tool calls.
Memory rule: feedback_background_tasks_multi_agent
Loop until done; only ask founder for real decisions
When stuff fails, retry/fix/loop. Don't ping for micro-decisions. Interrupt only for genuine product forks or destructive-action permission.
Memory rule: feedback_loop_until_done
Session-state snapshots written incrementally
Maintain a live 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.
Memory rule: feedback_save_session_at_end
Cognito: describe before update, never partial
AWS 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.
Memory rule: feedback_cognito_update_pool_replace_not_merge
PreToolUse pattern blocker
Dangerous shell patterns (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.
See docs/GUARDRAILS.md for the full pattern list
ONLY use sattvah-api. hissme-api is dead.
Backend lives at /Users/mano/Desktop/workspace/sattvah-api. hissme-api directory is legacy and forbidden territory. Never read, edit, or push to it.
Memory rule: feedback_only_sattvah_repo

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.

Claude Code session ~/.claude/projects/...jsonl Conductor + 5 agents work Stop hook : extractor claude -p, chunked Decisions, blockers, tasks Postgres + tsvector forge_memories Full-text search, GIN index SessionStart hook forge recall-context Injects every relevant memory UserPromptSubmit (opt) forge recall "<query>" Top-K hits per prompt extract write read prompt
Live flow: every turn from Claude triggers the extractor; every new session loads from Postgres.

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

  1. No API calls allowed. OpenAI embeddings require a network call to an external service. Hard rule, no exceptions.
  2. Postgres FTS is enough for chat-summary text. The extractor writes specific nouns ("Razorpay", "Sonnet", "₹1500"), and ts_rank retrieves 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.

TagSourceExample
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

create
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)

attach
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

A : Per-shell env var
Most precise. Isolates terminals.
export FORGE_PROJECT=wells
B : Machine-wide
Persists across shells. Good default.
forge project use wells
C : The launcher
Env + cd + exec claude, all at once.
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

ingest
# 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:

retag
# 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.

1
One terminal = one project
Set 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.
2
Always use forge p <slug> for new sessions
It sets the env, cds to the right repo, and execs claude. Three sources of error collapsed into one command. Use this 99% of the time. Plain claude is the exception.
3
Recall is scoped automatically
The SessionStart hook calls 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

audit
# 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
Spot a leak? Retag without re-ingesting. 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.

RequirementWhyInstall
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.
AWS is not required for local. Postgres runs in Docker on 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.
No API keys at any point. Not OpenAI, not Anthropic API, not an embeddings provider. Everything flows through claude -p, which uses your existing Claude Code auth.

Five minutes to running.

Clone, bootstrap, ingest, install the hooks, drop in the skills. Done.

bootstrap.sh
# 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.

If bootstrap fails with 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>.

terminal
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
  • execs claude --dangerously-skip-permissions (replaces the shell)

First launch, choosing the repo

first-time launch
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

FlagEffect
--hereUse current cwd as the repo (overrides saved path)
--in DIRUse the given dir as the repo
--newCreate the project if it doesn't exist
--no-skipDon't pass --dangerously-skip-permissions
--bin PATHOverride the claude binary location

System architecture.

Four moving parts, each replaceable in isolation.

Claude Code CLI claude --dangerously-skip... forge CLI (Go) cmd/forge/main.go launcher, ingest, recall Extractor internal/extractor chunked, 120K chars/chunk claude -p subprocess internal/llm/claude.go 15-min timeout / chunk Hooks (~/.claude/settings.local.json) SessionStart, Stop, UserPromptSubmit, PreToolUse Wire forge subcommands as event handlers Skills (~/.claude/skills/) /forge-recall, /forge-timeline, /forge-status Slash commands inside Claude Code Postgres 16 : tsvector + GIN
Four layers. The forge CLI is the only thing that talks to Postgres directly.

Repo layout

tree
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.

SessionStart
Fires once when a new Claude Code session begins. Calls forge recall-context, which detects the repo from cwd and injects every relevant memory into the system prompt.
Stop
Fires after every assistant turn. Calls forge ingest-current, which re-extracts the active session so memory grows live, no waiting for nightly cron.
UserPromptSubmit (opt)
Fires when user submits a prompt. Calls forge recall "<prompt>" for top-K full-text hits. Useful when you want query-aware injection per turn.
PreToolUse
Fires before any tool call. Calls 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

~/.claude/settings.local.json
{
  "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.

/forge-recall
Searches memory for any query. Returns markdown of top hits with file refs and timestamps.
/forge-timeline
Recent decisions, tasks, blockers across all projects. Filter by --days, --kind, --project.
/forge-status
Active project, DB connection, claude on PATH, memory counts per project, recent ingest activity.

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.

Sharing memory across machines Point 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.

CommandWhat 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-dbApply schema. Idempotent.
forge ingestScan transcripts, run claude -p to extract, store. Skips already-processed sessions.
forge ingest --days 30Lookback override.
forge ingest-currentRe-extract the active session. Use as a Stop hook.
forge recall "<query>"Postgres full-text search. Markdown out.
forge recall "<query>" --repo SLUGRestrict to one repo.
forge recall-contextSession-start hook entrypoint. Auto-detects cwd to repo. Unlimited window by default.
forge timelineRecent decisions + tasks + blockers, newest first.
forge timeline --days 30 --kind decisionFiltered timeline.
forge project new <slug>Create a strategic-project bucket.
forge project use <slug>Activate a project for the current shell.
forge project listShow 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 statusConfig + DB state. Verifies claude is on PATH.
forge install-hookAuto-merges SessionStart + Stop hooks into ~/.claude/settings.local.json. Idempotent.
forge install-cronPrints 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.