atomadic-forge 0.16.0

Atomadic Forge — absorb, enforce, emerge. Polyglot (Python · JavaScript/TypeScript · Swift · Kotlin · Go) architecture guardian for AI-generated code.

Atomadic Forge

The Copilot's Copilot — built by agents, for agents

Forge is the architecture substrate that Cursor, Copilot, Claude Code, Aider, Codex, and Devin call between turns. They generate code fast. Forge gives that code architectural gravity — deterministic, signed, mathematically-rigorous verification you can trust before you ship.

Forge holds zero LLM clients. The agent drives its own model; Forge supplies certainty. That boundary is the whole product.

# From any MCP-aware agent (Cursor, Claude Code, Aider, Codex, Devin, …)
auto({
  "target":  "/path/to/messy-repo",
  "output":  "/path/to/clean-output",
  "package": "my_pkg",
  "apply":   true
})
# → scout → cherry-pick → assimilate → wire → certify → signed receipt

One call returns a tier-organized, import-law-enforced, certify-scored package the agent continues building on. Forge keeps the law; the agent stays in the loop.

Why agents depend on it

	Cursor / Claude Code / Codex / Aider	+ Forge
Generate code	✅	(unchanged)
Verify architecture	❌	✅ wire + certify + verify
Cross-repo capability harvest	❌	✅ harvest + emergent_swarm (τ_trust gated)
Refuse wrong tier before write	❌	✅ preflight_change
Composite go/no-go ship gate	❌	✅ verify (PASS / REFINE / FAIL + next_command)
Signed conformance proof	❌	✅ Receipt v1

What just shipped (v0.16.0)

• Dress-rehearsal hardening — six bugfixes, eleven new tests (v0.16.0) — live stress-test on three real Python repos (atomadic-forge, langgraph, crewai) ahead of the Boris demo surfaced six bugs across the synthesis, planning, summary, and pipeline-pipe surfaces. emergent synthesize no longer emits broken from pkg.mod.Class import method; forge plan no longer suggests a literal your_pkg placeholder; forge score-patch --file - honours the stdin sentinel; forge sbom text summary reports the real component count; recon-swarm/emergent-swarm/guard-install register both hyphen and underscore forms so commandsmith smoke is 100% green; synergy-then-emergent and emergent-then-synergy pipes use the real --save FILE flag. Single-seed forge create jumped from certify=60/FAIL to certify=90/100 with importable code on first generation. Test suite 1,291 → 1,302 passed.

What previously shipped (v0.15.0)

From spaghetti to shippable in one command. forge create takes an intent and a list of seed repos and returns a pip-installable Python package: it scans, finds emergent compositions, materializes the top candidates, runs wire + certify, and writes the receipt. Deterministic, no LLM, no network. pip install atomadic-forge to try it.

• forge create — intent + seed repos → shippable Python package (v0.15.0) — one-command pipeline composing existing primitives. Resolves each seed (auto-detects src/<pkg>/ layout, tier-bearing dir, or single-package roots), runs emergent_swarm across the union, persists scan + receipt to .atomadic-forge/, then pipes top-N candidates through materialize for the final package. Strictly local paths — no GitHub cloning, no third-party absorption. End-to-end smoke on Forge itself: 570-symbol union catalog → 25 candidates → 17-file package, wire_violations=0.
• forge materialize — emergent scan report → shippable package (v0.15.0) — turns an emergent scan JSON into a tier-organized scaffold (a0..a4 with __init__.py), pyproject.toml, README.md, .gitignore, tests/conftest.py, plus one a3 feature module + smoke test per selected candidate. Slug uniqueness via candidate-id tail so name collisions don't overwrite. Optional wire-check + certify pass with the verdict embedded in the report. Refuses to overwrite a non-empty unrelated directory.
• forge hive recap — full lifecycle replay of one consensus (v0.14.0a10) — new CLI verb + MCP tool (hive_recap, surface 60 → 61). Returns proposer, proposed_at, intent, every vote (with rationale + timestamp), the resolution event if any, and a summary block (verdict, duration, voters). The "what happened on this consensus?" primitive — useful for audit trails, release-note quotes, post-mortem replay.
• forge hive needs-vote — "what should I weigh in on?" (v0.14.0a9) — new CLI verb + MCP tool (hive_needs_vote, surface 59 → 60) returning open consensuses where the calling agent hasn't voted yet, ordered by proposed_at, with votes_so_far + voters_so_far context. Closes the gap between hive_observe (everything happening) and the act of voting. Doc agent used it immediately after release to discover its own proposal needed proposer-vote attention.
• docs/WORLD_COLLISION.md (v0.14.0a8) — the 11-step E2E walkthrough of Atomadic-uses-Forge. Six of the eleven steps have already fired this sprint with public-artifact evidence (wisdom.jsonl + hive/consensus.jsonl). Forge agent authored.
• The 7 LIVE AAAA-Nexus primitives are now MCP tools (v0.14.0a7) — nexus_identity_verify, nexus_federation_mint, nexus_authorize_action, nexus_sys_trust_gate, nexus_contract_verify, nexus_lineage_record, nexus_ratchet_register. Surface jumps 52 → 59 tools. Any MCP-aware agent (Cognition, Cursor, Claude Code) calls them directly through Forge — no CLI --nexus flag round-trip. All seven proxied through NexusClient.from_env() with auth-precedence (subscription > master) and the same NexusToolNotShipped guard.
• forge hive result --nexus — consensus → Nexus mirror (v0.14.0a6) — extends the hive↔Nexus bridge from wisdom-only (v0.14.0a5) to also mirror consensus resolution events. Fires only on freshly-recorded resolutions; best-effort, local stays canonical on failure.
• Hive ↔ Nexus bridge — live primitives only (v0.14.0a5) — forge wisdom record --nexus mirrors confidence-≥0.85 wisdom entries to AAAA-Nexus's LIVE lineage_record primitive. New a0/nexus_constants.py enumerates the 7 LIVE primitives Cognition's handshake confirmed exist; a2/nexus_client.py raises NexusToolNotShipped on any call outside that set. The LoRA capture loop closed against the actually-deployed Nexus, not the planned-but-vapor surface.
• forge hive watch — live tail of hive activity (v0.14.0a4) — color-coded continuous tail of hive_observe. New events every --interval seconds (proposals cyan / approve votes green / refine yellow / reject red / resolutions bright-green bold / wisdom-new ✦ / wisdom-superseded ↺). The synchronized-message-demo surface — Thomas (or any operator) can watch the four agents coordinate in real time.
• Relay protocol aligned with REAL Nexus surface (v0.14.0a3) — Cognition agent's WIS-cog-2026-05-06-handshake wisdom entry surfaced that the AAAA-Nexus primitives v0.14 was originally designed against (nexus_consensus_*, nexus_swarm_*, nexus_agent_*) don't exist on the deployed Worker. Forge agent re-wrote RELAY_PROTOCOL.md against the 7 live primitives (identity_verify, federation_mint, authorize_action, sys_trust_gate, contract_verify, lineage_record, ratchet_register). The hive caught a design-against-vapor moment via public-artifact corroboration — no Thomas-relay required.
• Relay wire-contract spec (v0.14.0a2) — docs/RELAY_PROTOCOL.md defines endpoints, JSON-RPC envelope shape, audit-log format, and Worker-side enqueue pattern.
• forge relay serve — Worker → Local relay (alpha) (v0.14.0a1) — first half of the "no stubs fully Forge-compatible" goal. A thin stdlib HTTP service (forge relay serve --host 127.0.0.1 --port 7409) that receives signed JSON-RPC envelopes and dispatches them through mcp_protocol.dispatch_request. The Worker side ships separately; when both halves are live, the 12 currently-stubbed Worker tools become real. Audit log at .atomadic-forge/relay/jobs.jsonl.
• hive_observe goes multi-source (v0.13.4) — one call now merges wisdom events (wisdom.new / wisdom.superseded) AND consensus events (consensus.proposed/vote/resolved), filtered by the agent's subscribes_to set, with two independent cursors (since_consensus_id + since_wisdom_id). Live cross-stream view of hive activity since the agent's last sync.
• Wisdom → recipe promotion (v0.13.3) — forge wisdom promote (CLI) and wisdom_promote (MCP, 51 → 52 tools) cluster active wisdom by tag overlap; clusters with ≥3 corroborated entries become draft-recipe candidates at _private/research/recipe_drafts/<name>.md. The bridge between provisional knowledge and curated process.
• Hive sync pipeline (v0.13.2) — 7 MCP tools (hive_register / hive_observe / hive_propose / hive_vote / hive_result / hive_list / hive_deactivate). The register-and-discover protocol that lets four-agent loops coordinate via append-only public artifacts — no direct messaging. Foundation for the Atomadic-as-sovereign-AI endpoint. Full reference: docs/HIVE_PRIMITIVES.md.
• tool_factory kwargs-binding fix (v0.13.2) — keyword-only impl signatures now register cleanly via tool_factory(apply=true).
• Wisdom DB on the MCP surface (v0.13.1) — wisdom_record / wisdom_query / wisdom_list / wisdom_recall are first-class MCP tools. Any MCP-aware agent (Cognition, Cursor, Claude Code, Aider, Codex, Devin) can record / query / recall institutional memory directly.
• Wisdom DB (v0.13.0) — cross-session institutional memory at .atomadic-forge/wisdom.jsonl. Auto-hooks bracket every dev cycle: forge recon returns prior_wisdom; forge verify returns wisdom_capture_prompt. Agents inherit prior lessons without extra discipline; the substrate persists across conversations.
• Canonical surface artifact (v0.12.0) — forge surface emit/check/diff + surface.json checked into the repo + CI gate (surface-drift.yml). Every consumer reads the artifact; hand-maintained maps are gone. legacy_endpoint_map lets stale callers find renamed tools without a separate lookup.
• __version__ drift fix (v0.12.0) — derived from importlib.metadata so pyproject.toml is the one source of truth. The v0.11.0 drift (pyproject 0.11.0, __init__ 0.10.0) is structurally impossible going forward.
• Polyglot expansion (v0.11.0) — Swift, Kotlin, Go, .mts, .cts join Python and JS/TS. One pass, no language servers, no Node dependency.
• Surface consolidated in v0.10.0 — 47 → 40 tools, zero capability lost. Merged audit_list + why_did_this_change + what_failed_last_time → lineage; list_recipes + get_recipe → recipes; auto_plan + adapt_plan → plan; auto_step + auto_apply → plan_apply.

---

Absorb. Enforce. Emerge. The architecture substrate for AI-generated code — now polyglot (Python, JavaScript / TypeScript, Swift, Kotlin, Go).

🔗 Try it live: forge.atomadic.tech — paste any GitHub repo and watch the analysis in real time.

Forge is a monadic-architecture engine that does three things no existing tool combines:

1. Absorbs Python, JavaScript / TypeScript, Swift, Kotlin, or Go repositories into a verified 5-tier layout.
2. Enforces the upward-only import law on every emitted file.
3. Emerges new capabilities by composing what already exists — and refuses to credit code that lies about what it does.

It's the substrate Cursor and Devin and Lovable don't have. It runs on free local models, free cloud tiers, or paid frontier models — same loop, swap the LLM, watch the trajectory carry harder tasks higher.

Five capabilities no other tool ships today:

Capability	Why it matters
verify	Single composite go/no-go ship gate — runs wire + certify (and optionally score_patch + preflight_change) and returns PASS / REFINE / FAIL with a recommended next_command. One call answers "is this ready?"
emergent_scan	Cross-domain composition discovery — finds novel a3 features you can ship by wiring existing symbols, without writing new logic
harvest	Cross-repo capability gap-finder. Diffs target against N≤23 sibling repos, ranks graft candidates by τ_trust-gated confidence (≥0.998354 → auto-applyable, below → review_required)
preflight_change	ASK BEFORE WRITING — surfaces wrong tier, forbidden imports, and scope violations before the agent generates a single line
Receipt v1	Signed conformance proof — JSON artifact CI, regulators, and downstream agents accept as evidence the package passed every gate

Languages: Python (.py), JavaScript (.js / .mjs / .cjs / .jsx), TypeScript (.ts / .tsx / .mts / .cts), Swift (.swift), Kotlin (.kt / .kts), Go (.go). Cloudflare Workers, Node back-ends, native mobile apps, and mixed-language repositories all classify in a single pass — no Node dependency, no kotlinc, no swiftc, node_modules/ skipped automatically.

Get started in 10 minutes

Read docs/FIRST_10_MINUTES.md. It is the canonical onboarding path: install, a 30-second offline demo, a 10-second free recon on your own repo, then a fork into either "absorb existing code" or "generate from intent" with explicit cost, privacy, and wallclock numbers.

For deeper paths once you have done the 10-minute path:

• docs/HIVE_STATUS.md — live status board for the four-agent loop (Forge, Cognition / Atomadic, Doc, Research). Read first if you're an agent activating into this repo.
• docs/HIVE_PRIMITIVES.md — the 7 hive_* MCP tools (register, observe, propose, vote, result, list, deactivate). The register-and-discover protocol that lets agents coordinate without direct messaging.
• docs/RELAY_PROTOCOL.md — wire contract between Worker MCP and forge relay serve. Endpoints, JSON-RPC envelope shape, audit-log format, Worker-side enqueue pattern.
• docs/WORLD_COLLISION.md — the 11-step E2E walkthrough of Atomadic-uses-Forge. The autonomous loop the four-agent hive is running toward.
• docs/02-commands.md#forge-surface — emit, verify, and diff the canonical surface.json artifact (CI gate + consumer bootstrap).
• docs/02-commands.md#forge-wisdom — append-only institutional memory: record lessons, query across sessions, auto-recall on recon.
• docs/WORKER_VS_LOCAL_MCP.md — two MCP servers, two contracts: when to call which, and the args each accepts.
• docs/MULTI_REPO.md — absorb more than one repo at once.
• docs/CI_CD.md — GitHub Actions, GitLab CI, pre-commit.
• docs/AIR_GAPPED.md — offline / on-prem install.
• docs/SHOWCASE.md — live trajectories of real runs.
• docs/MARKET_POSITIONING.md — why Forge matters in the AI coding market.
• docs/RELEASE_MESSAGING.md — launch copy, HN post, outreach, and demo script.

Polyglot recon (JS/TS in a single pass)

$ forge recon ./my-cloudflare-worker

Recon: ./my-cloudflare-worker
------------------------------------------------------------
  python files:     0
  javascript files: 4
  typescript files: 1
  primary language: javascript
  symbols:          17
  tier dist:        {'a0_qk_constants': 1, 'a1_at_functions': 2,
                     'a2_mo_composites': 1, 'a4_sy_orchestration': 1}
  effect dist:      {'pure': 9, 'state': 5, 'io': 3}
  recommendations:
    - JS/TS files are not yet split into aN_* tier directories —
      see suggested_tier per file in symbols[].

Pipeline lanes

forge create -i "<intent>" -s ./repo -o ./out --package my_pkg  # NEW: emergent → pip-installable, deterministic
forge auto ./messy-repo ./out --apply                            # Absorb a flat repo into 5-tier layout
forge evolve run "<intent>" ./out --auto 5                       # LLM-driven recursive generation
forge demo run --preset NAME                                     # Click-to-launch-video preset
forge chat ask "what should I fix next?" --context .

What Forge does:

• Walks any Python or JavaScript/TypeScript repo, classifies every symbol into one of 5 architectural tiers
• Materializes into a tier-organized tree with strict upward-only imports
• Detects architecture violations (upward imports, misclassified symbols) — Python or JS, same law
• Scores conformance: documentation, tests, tier layout, import discipline
• Works with AI-generated code — absorbs it, fixes the architecture, ships it

What Forge does NOT do:

• Pretend forge auto magically finished your product; absorption creates a tiered starter skeleton. iterate / evolve can generate code through your configured LLM, but Forge still gates it with wire/certify feedback.
• Create semantic unification (two User classes stay two User classes)
• Bypass the 5-tier law (Forge itself passes its own wire scan 100%)
• Store secrets or credentials

Why Forge exists

AI agents produce 30–50% of new code in many teams. The output is fast and often correct. But it's almost universally architecturally incoherent:

• God classes mixing concerns
• Leaky abstractions and circular imports
• Same concept named five different ways
• Test coverage is scattered
• No module organization

Linters say "no." Forge says "yes, but reorganised like this" and shows the diff.

Forge is not a style checker. It's an architecture rebuilder. It absorbs your code (including AI-generated code), re-tiers it, enforces the 5-tier monadic law, and emits a clean, verifiable structure with certification scores.

Release positioning: AI coding agents create implementation velocity. Forge adds architectural gravity. See docs/MARKET_POSITIONING.md for the market frame and source-backed claims.

The 5-tier monadic law

Every source file (Python .py, JavaScript .js/.mjs/.cjs/.jsx, or TypeScript .ts/.tsx) belongs to exactly one tier. Tiers compose upward only — never sideways, never downward.

  a4_sy_orchestration/       ← CLI, entry points, top-level orchestration
           ↑
  a3_og_features/            ← Feature modules (compose a2 into capabilities)
           ↑
  a2_mo_composites/          ← Stateful classes (clients, registries, stores)
           ↑
  a1_at_functions/           ← Pure functions (validators, parsers, formatters)
           ↑
  a0_qk_constants/           ← Constants, enums, TypedDicts (zero logic)

Tier	Directory	What lives here	May import
a0	a0_qk_constants/	Constants, enums, TypedDicts, config	Nothing
a1	a1_at_functions/	Pure stateless functions	a0 only
a2	a2_mo_composites/	Stateful classes, clients, stores	a0, a1
a3	a3_og_features/	Features combining composites	a0–a2
a4	a4_sy_orchestration/	CLI commands, entry points	a0–a3

Why the tiers work

Each tier is a layer of verified building blocks. Higher tiers never invent logic — they compose blocks from lower tiers. This means:

• a0 is bulletproof: no imports, no logic, 100% verifiable
• a1 is isolated: pure functions on pure data, trivial to test
• a2 wraps logic: state + verified building blocks, testable in isolation
• a3 orchestrates: combines composites into features, handles cross-cutting concerns
• a4 glues everything: CLI layer only, zero business logic

Upward-only import law: forge wire detects violations, import-linter enforces at CI, contract lives in pyproject.toml.

Installation

pip install atomadic-forge
forge --version   # atomadic-forge 0.15.0
forge doctor      # environment check

60-second quickstart (v0.15.0)

From a fresh pip install, take any tier-organized repo and produce a new pip-installable package containing emergent compositions:

# 1. Discover and ship in one call
forge create \
    --intent "logging-aware retry layer" \
    --seed-repo /path/to/your/repo \
    --out-dir   ./out/retry_layer \
    --package   retry_layer \
    --top-n 5

# Output:
#   union catalog:      <symbols-scanned>
#   candidates:         <novel-compositions-found>
#   files written:      <scaffold + features + tests>
#   wire violations:    0
#   certify:            <score>  (PASS / REFINE / FAIL)
#
# Receipt: ./out/retry_layer/.atomadic-forge/create.json
# Scan:    ./out/retry_layer/.atomadic-forge/scan.json

Need finer control? The same pipeline is two steps:

forge emergent scan --top-n 25 --save scan.json    # discovery
forge materialize run scan.json ./out/retry_layer \\
    --package retry_layer --top-n 5                # ship

Then follow docs/FIRST_10_MINUTES.md for the canonical first-run path (offline demo, free recon, then absorb or generate).

From source (contributors):

git clone https://github.com/atomadictech/atomadic-forge && cd atomadic-forge
pip install -e ".[dev]"
python -m pytest               # 1293 collected (1291 passed, 2 skipped)

AI Agent integration (MCP)

Forge ships a Model Context Protocol server — add it to Cursor, Claude Code, Aider, Devin, or any MCP-compatible agent and they can drive forge without touching the CLI:

{
  "mcpServers": {
    "atomadic-forge": {
      "command": "forge",
      "args": ["mcp", "serve", "--project", "/path/to/your/repo"]
    }
  }
}

All 66 MCP tools (local) · 40 on the deployed Worker

Recommended first call: welcome — runs scout + certify + wire on the current repo and returns a structured situation report (score, top strengths, top priorities, suggested next call, agent guidance, capability tour, safety net). Surfaced to MCP clients via serverInfo.recommended_first_call and a per-tool recommended_first_call: true flag in tools/list.

Grouped by purpose. Every tool is tools/call-able through the MCP contract; every tool returns a versioned schema (atomadic-forge.<tool>/v<n>). Run forge mcp serve --help for the full surface with examples.

Pipeline (the agent's normal day)

Tool	One-liner
recon	Walk a repo and return a structured scout report (symbols, tier guess, effects).
context_pack	First-call repo bundle: score, blockers, risky files, best next action.
preflight_change	ASK BEFORE WRITING. Tier + import + scope check on a proposed edit.
wire	Detect upward-import violations across the tier graph.
certify	0–100 go/no-go score with structural / runtime / behavioral / operational breakdown.
verify	Composite ship gate. Runs wire + certify (+ optional score_patch + preflight_change). Returns PASS / REFINE / FAIL + next_command.
score_patch	Predict certify-score impact of a unified diff before committing.
select_tests	Pick the smallest validation set that exercises the changed files.
enforce	Tier-law enforcement gate — fails loud on regressions.
rollback_plan	Reversal recipe for a proposed change (what to undo, in what order).

Auto-pipeline (one-call absorb, plan, apply)

Tool	One-liner
auto	Flagship one-shot: scout → cherry → assimilate → wire → certify. Used most.
plan	Generate a bounded execution plan (action cards with risk + rollback annotations).
plan_apply	Apply one card or all-applyable cards from a plan result.
iterate_start	Begin an LLM-driven iterate loop. Forge holds zero LLM clients — caller drives.
iterate_continue	Step the iterate loop. Each turn is observable; rollback is cheap.
evolve_start / evolve_step	Recursive iterate — each round seeds the next from the prior output.
cherry	Cherry-pick manifest of symbols from a scouted repo. Surgical control.
finalize	Materialize a cherry-pick into a tier-organized output package.

Cross-repo intelligence (Round-4 / Round-5)

Tool	One-liner
recon_swarm	Walk N≤23 repos and return a unified scout report.
harvest	τ_trust-gated graft proposals — capabilities your target lacks but your portfolio has.
emergent_swarm	Cross-repo emergent composition discovery. Finds new a3 features hiding in the union.
guard_install	Install the four-layer architectural immune system: pre-commit + GH Action + pyproject + CONTRIBUTING.

Code intel + audit

Tool	One-liner
emergent_scan	Cross-domain composition discovery on a single repo.
synergy_scan	Pairs of symbols whose composition exceeds the sum of parts.
cna_check	Compose-Not-Add. Flag features added when an existing composite would have served.
call_graph	Static call graph (Python + JS/TS), tier-coloured.
smell_scan	Architectural smells beyond simple tier-violations.
manifest_diff	Manifest-level diff between two scouts (added / removed / migrated symbols).
lineage	Decision audit — what changed, why, what failed last time. (Auto-detects mode from args.)
commit_compose	One-call Conventional Commit message builder from staged diff + intent.
forge_locate	Return the line range of well-known forge insertion points (saves ~1000 tokens vs reading the file).

Meta + ops

Tool	One-liner
recipes	Named golden-path recipes (add_feature, bump_version, dev_cycle, release_hardening, …). No name = catalogue; with name = full body.
tool_factory	Forge eats forge — meta-tool that scaffolds new MCP tools from a spec.
doctor	Health check; include_worktree=true adds worktree status.
sidecar_validate	Sidecar-mode contract test.
compose_tools	Compose multiple tools into a higher-level workflow.
explain_repo	Plain-English orientation for a repo.
load_policy	Load a custom certify / wire policy.
trust_gate_response	Trust-gate envelope for any agent response.

v0.10.0 surface consolidation: lineage merges audit_list + why_did_this_change + what_failed_last_time; plan merges auto_plan + adapt_plan; plan_apply merges auto_step + auto_apply; recipes merges list_recipes + get_recipe. doctor absorbs worktree_status (via include_worktree=true); verify absorbs exported_api_check (via check_exports=true). 47 → 40 tools, zero capability lost.

5 resources: Receipt schema · formalization docs · lineage chain · blocker summary · verdicts

forge mcp serve --help   # full tool + resource listing with examples
forge mcp doctor --project . --json

As of 0.5.2, tools/list includes a cli_command fallback for each MCP tool. context-pack, preflight, select-tests, and score-patch also use language-aware validation commands so JavaScript projects get npm run verify / npm test guidance and documentation/research paths are treated as non-code project memory.

Subscription required for forge mcp serve

Every tools/call against the MCP server is gated behind a paid Forge subscription. Get a key at https://atomadic.tech/forge, then run:

forge login                          # interactive: paste your fk_live_* key
export FORGE_API_KEY=fk_live_xxxxx   # or set the env var directly
forge mcp serve --project .

Read-only handshake methods (initialize, ping, tools/list, resources/list) work without a key so MCP clients can complete the connect handshake; tools/call and resources/read require an active subscription. The verify endpoint at https://forge-auth.atomadic.tech/v1/forge/auth/verify is contacted on first call and the result is cached for 5 minutes; offline grace keeps you running for 24 hours after the last successful verify.

Without a key (or with a revoked one), tools/call returns the JSON-RPC error code -32001 with message="Forge subscription required" and an upgrade_url pointing back to the dashboard.

Code-from-intent (LLM-driven, with Forge as the architectural backbone)

Plug a free Gemini key in and let the loop produce architecturally-coherent code from a paragraph of intent:

# Get a free key at https://aistudio.google.com/apikey
export GEMINI_API_KEY=your-key-here          # never commit this

# Single-shot generate (one user-intent → multi-turn LLM loop):
forge iterate run "build a tiny calculator CLI" ./out \
    --package calc --provider gemini --max-iterations 4

# Recursive self-improvement: N rounds, catalog grows each round:
forge evolve run "build a markdown-to-PDF service" ./out \
    --auto 5 --provider gemini --target-score 80

# Pre-flight (no LLM call) — print the system + first prompt:
forge iterate preflight "..." --package whatever

Every Python iterate / evolve run now ends with a deterministic quality phase: Forge adds conservative missing docstrings, writes docs/API.md and docs/TESTING.md, and creates tests/test_generated_smoke.py so the package has import-smoke coverage even when the model forgets tests. These generated tests are a floor; add behavior tests for real inputs before shipping.

Chat copilot

Use your configured AI agent as a Forge-aware terminal copilot. The chat surface uses the same provider layer as iterate and evolve, and can pack bounded repo context without sending .env or obvious secret files.

# One-shot question with repo context
forge chat ask "what should I run before release?" --context .

# Interactive session against your AAAA-Nexus agent
export AAAA_NEXUS_API_KEY=...
forge chat repl --provider nexus --context src --context docs

# Offline smoke test for scripts / CI
forge chat ask "hello" --provider stub --no-cwd-context --json

LLM provider matrix

Provider	Cost	Env var	Default model	When to use
gemini	free tier	GEMINI_API_KEY / GOOGLE_API_KEY	gemini-2.5-flash	Best free cloud option; override with FORGE_GEMINI_MODEL
nexus / aaaa-nexus	paid	AAAA_NEXUS_API_KEY	(Nexus default)	AAAA-Nexus sovereign AI; most reliable for long runs
anthropic	paid	ANTHROPIC_API_KEY	claude-sonnet-4-6	Highest code quality (Claude 4.x; override with claude-opus-4-7 for max reasoning or claude-haiku-4-5-20251001 for speed)
openai	paid	OPENAI_API_KEY	gpt-4o-mini	Cheap GPT path; override to gpt-4.1 or gpt-4o for higher quality
openrouter	free tier available	OPENROUTER_API_KEY	inclusionai/ling-2.6-1t:free	Access 200+ models; good fallback when Gemini quota exhausted; override with FORGE_OPENROUTER_MODEL
ling	free	OPENROUTER_API_KEY	inclusionai/ling-2.6-1t:free	Shortcut for Ling-2.6-1T (1T-param MoE, 262K ctx, SOTA SWE-bench) — frontier model at zero cost via OpenRouter
ollama	free, local	FORGE_OLLAMA=1	qwen2.5-coder:7b	Offline; fully private
stub	free, offline	n/a	n/a	Tests, CI, dry-runs

--provider auto resolves in the code-defined order: AAAA-Nexus, Anthropic, Gemini, OpenAI, OpenRouter, Ollama, then stub. Explicit --provider gemini (or any other provider name) always wins.

For busy laptops or desktops, run Ollama with the small local profile:

export FORGE_OLLAMA=1
export FORGE_OLLAMA_MODEL=qwen2.5-coder:1.5b
export FORGE_OLLAMA_NUM_PREDICT=768
export FORGE_OLLAMA_TIMEOUT=180
forge chat ask "what should I fix next?" --provider ollama --context src

Use qwen2.5-coder:7b when the machine is idle and you want better code quality. FORGE_OLLAMA_NUM_PREDICT caps each generation; lower it if Ollama starts paging or crashing. FORGE_OLLAMA_TIMEOUT controls how long Forge waits before returning a clear provider error.

Commands

Flagship: forge auto does everything in one shot.

Absorb pipeline

Command	Purpose	Typical use
forge auto	Scout → cherry-pick → materialize → wire → certify. The main verb.	forge auto ./repo ./out --apply
forge recon	Walk a repo, classify every symbol. Shows tier distribution.	forge recon ./repo
forge cherry	Build a cherry-pick manifest. Select specific symbols or --pick all.	forge cherry ./repo --pick all
forge finalize	Materialize, wire, certify. Run separately if needed.	forge finalize ./repo ./out --apply
forge wire	Scan a tier tree for upward-import violations.	forge wire ./out/src/package
forge certify	Score: documentation, tests, tier layout, import discipline.	forge certify ./out --fail-under 90
forge enforce	Apply F-code-routed mechanical fixes (rollback-safe).	forge enforce ./out/src/package
forge status	Wire + certify in one call. The quick health check.	forge status .

Observability & compliance

Command	Purpose
forge audit list / show / log	Browse .atomadic-forge/lineage.jsonl — run history, saved manifests.
forge doctor	Environment check — Python, optional deps (complexipy, cryptography).
forge sbom	Emit a CycloneDX 1.5 SBOM from the scout report.
forge cs1	Render a Conformity Statement (EU AI Act / SR 11-7 / FDA PCCP / CMMC-AI).
forge diff	Schema-aware compare of two scout or certify manifests.
forge sidecar parse / validate	Parse + cross-check .forge v1.0 sidecar grammar.

Agent & LLM loops

Command	Purpose
forge mcp serve	Stdio JSON-RPC MCP server — 66 tools for Cursor / Claude Code / Aider / Devin.
forge plan / plan-list / plan-show / plan-step / plan-apply	Agent plan persistence and step-by-step apply.
forge iterate	LLM loop: intent → code → absorb → wire → score → iterate. Single shot.
forge evolve	Recursive improvement: N rounds, catalog grows each round.
forge chat	Terminal copilot over forge docs/source using the same AI provider layer.
forge context-pack	Pack bounded repo context for first-call orientation or targeted change/release/debug focus.
forge worktree status	Check branch, upstream drift, dirty files, version sync, and stale installed forge commands before editing.
forge preflight	Pre-edit guardrail — forbidden imports, tier checks.
forge recipes	List and fetch golden-path recipe templates.

Composition & tooling

Command	Purpose
forge emergent scan	Symbol-level composition discovery — find type-safe chains across modules.
forge materialize (v0.15.0+)	Turn an emergent scan report into a real, pip-installable Python package with proper tier layout.
forge create (v0.15.0+)	One-command pipeline: intent + seed repos → scan → materialize → certify.
forge synergy	Feature-pair detection + auto-generate adapters.
forge harvest	Cross-repo capability gap finder, τ_TRUST gated.
forge recon-swarm / forge emergent-swarm	Multi-repo recon + cross-repo composition discovery.
forge commandsmith	Auto-register CLI commands, regenerate _registry.py, smoke-test all verbs.
forge lsp serve	Stdio LSP server for .forge files (live diagnostics, hover, goto).

Targeted workflows

Forge ships several distinct lanes — pick the one that fits your intent.

Lane 1 — Orient and certify an existing repo (read-only)

forge welcome                # one-shot: scout + certify + wire + agent guidance
forge recon .                # tier distribution, effect distribution, recommendations
forge certify .              # 4-axis score (docs / tests / layout / wire)
forge status .               # one-line wire + certify summary
forge explain-repo           # JSON orientation packet (one-liner / do_not_break / release_state)
forge context-pack           # bounded LLM-ready repo briefing

Lane 2 — Absorb a third-party repo into a tier-clean Atomadic package

# Dry-run first — see what would happen
forge auto ./external-repo ./absorbed --package external_pick

# Then commit
forge auto ./external-repo ./absorbed --package external_pick --apply
# 1854 symbols absorbed · wire PASS · proper a0..a4 layout

Lane 3 — (v0.15.0+) Build something new from emergent compositions

# Single-repo: discover compositions in your own catalog
forge emergent scan --src-root src --package myapp --save scan.json
forge materialize run --report scan.json --out-dir ./toolkit \
                      --package toolkit --top-n 5

# Cross-repo: synthesize a brand-new package from N seeds
forge create -i "agent toolkit from forge + crewai" \
             -s ./atomadic-forge \
             -s ./crewai/lib/crewai \
             --out-dir ./agent_toolkit \
             --package agent_toolkit --top-n 5
# 18 cross-repo chains · 5 picks · 21 files · wire PASS · certify 60→90

Lane 4 — LLM-driven generation under the architectural backbone

forge iterate run --intent "..." --out ./out         # one shot: intent → code → score → iterate
forge evolve   run "..." ./out --auto 3              # recursive improvement, N rounds
forge demo     run --preset calc                     # canned 50s autonomous build
forge chat                                           # terminal copilot over forge docs/source

Lane 5 — Cross-repo discovery and composition

forge recon-swarm     -r ./repo-a -r ./repo-b -r ./repo-c
forge emergent-swarm  -r ./repo-a -r ./repo-b -r ./repo-c
forge harvest         -t ./target -s ./source-a -s ./source-b

Lane 6 — Targeted spot-fixes

forge recon ./repo                                        # see what's in a repo
forge cherry ./repo --pick infer_tier --pick CherryPicker # pick specific symbols
forge cherry ./repo-a --pick all
forge finalize ./repo-a ./out --apply --on-conflict rename # merge two repos
forge enforce ./out/src/package --apply                    # mechanical fixes (rollback-safe)

Lane 7 — Coordination, lineage, governance

forge handoff create --agent X --work "..." --pytest-summary "..."
forge wisdom record --insight "..." --tags "..."
forge wisdom query --text "certify"
forge audit list                                # browse .atomadic-forge/lineage.jsonl
forge enhancement propose -t "..." -d "..."
forge surface emit --out surface.json           # canonical tool surface for drift CI
forge sbom .                                    # CycloneDX 1.5 SBOM
forge cs1                                       # EU AI Act / SR 11-7 / FDA PCCP / CMMC-AI conformity

Known limits (honest & concrete)

Forge ships with named limits. No overpromise.

1. Python and JavaScript/TypeScript today; Rust / Go on the roadmap. As of 0.2, recon, wire, and certify classify .py, .js, .mjs, .cjs, .jsx, .ts, and .tsx. The runtime-import smoke check (the +25 score component for "package actually loads in a fresh subprocess") and the behavioural pytest gate remain Python-only — JS/TS packages are scored on documentation, tests-present, tier layout, and upward-import discipline. The JS parser is regex + brace-walking, not a real AST; it handles the surface (imports, exports, class signals, Worker default-{ fetch, scheduled } shape) the tier law cares about.

2. Building material, not shipping software. forge auto output is a tier-organised starter skeleton, not a deployable app. Every --apply emits STATUS.md listing required follow-up:

   • Integration tests against real inputs
   • Runtime configuration (secrets, env vars, DB URLs)
   • Observability (logging, metrics, tracing)
   • Cross-symbol reconciliation (two User classes need unification, not duplication)

3. Tier classification is heuristic. Forge uses word-boundary tokens + body-state detection (mutable instance variables in Python; class declarations + module-level let/var in JS). The scout report logs the rationale per symbol so you can override misclassifications via --override-tier.

4. No semantic merge. Two class User from different repos don't auto-unify. Forge detects the collision via --on-conflict (rename | first | last | fail) and reports it. You decide how to reconcile.

5. Auto-generated adapters are scaffolding. The synergy pipeline emits adapters marked with # REVIEW: blocks. Read them. Refine them. They're templates, not production code.

6. Certificates are locally signed only. Ed25519 signing via forge certify --local-sign is available (requires pip install cryptography). Chain-of-custody / notarization infrastructure is a future milestone.

Design philosophy

• Absorb-first, generate-never. Forge never writes code from scratch. It absorbs and reorganises code that already exists — including AI-generated code.

• Dry-run by default. No verb writes to disk without --apply or equivalent. Only .atomadic-forge/ manifests (diagnostic reports) are written in dry-run mode.

• The 5-tier law is non-negotiable. Anything that ships with Forge passes its own wire scan. Forge's 193 source files live in a0–a4; it eats its own dogfood.

• Honest output. Every report includes schema_version. Every apply emits STATUS.md (required follow-up). Every artifact is provable and traced (lineage recorded in .atomadic-forge/lineage.jsonl).

• Composability, not coupling. Forge outputs JSON manifests at each stage (scout, cherry, assimilate, wire, certify). Pipe them. Script them. Build on them.

Atomadic family

Product	What it is	Status
AAAA-Nexus	Trust/safety/payments substrate for autonomous agents	Live at atomadic.tech
Atomadic Forge	Absorb-and-emerge engine for developers (this repo)	v0.15.0 — on PyPI, 1291 tests, 100/100, MCP server (66 tools local · 40 on Worker), forge create / forge materialize shippable-package pipeline, four-agent hive primitives, AAAA-Nexus bridge, agent-to-agent handoffs
Atomadic Assistant	Sovereign AI assistant with cognitive loop on Cloudflare	In development

Pricing

Free for OSS / non-commercial. Paid hosted MCP at forge.atomadic.tech/mcp for production agents.

Tier	Price	What you get
Free	$0	OSS, 25 calls/day, read-only tools
Pro	$79/mo	All 66 tools, 5k calls/mo, signed receipts, custom recipes
Studio	$249/mo	+ AAAA-Nexus notarization, compliance attestations, cross-repo telemetry, priority queue
Lifetime Founder	$999 once	One key. Forever. Forge Pro + Forge Deluxe (when launched) + AAAA-Nexus + every future Atomadic product. First 25 only.
Enterprise	custom	BSL commercial license, SSO, self-host, SLA

See forge.atomadic.tech/pricing for the live tier matrix.

Pay-per-call (x402) and prepaid call packs ($25 / $100 / $500 / $2,500) are also available on the hosted MCP.

License

Business Source License 1.1. Free for non-production use. Commercial license required for production — see COMMERCIAL_LICENSE.md. Change Date: 2030-04-27 → Apache 2.0.

Documentation

• Showcase — Live runs with live results (start here)
• Landscape — How Forge sits next to Cursor / Devin / Lovable / Copilot Workspace
• Why now — The urgency case for an architecture substrate
• Commands — Full reference for all 26+ verbs
• Release checklist — Shippability gates, CLI scenarios, local-model smoke checks
• Roadmap — 0.2 / 0.3 / 1.0 milestones
• Architecture guide — How Forge itself is built (monadic tiers, data flows, design)
• Security policy — Private vulnerability reporting and secret-handling expectations
• Tutorials — Quickstart, your-first-package, the 5-tier law, plug-in-LLMs, multi-repo absorb
• Contributing guide — How to extend Forge
• Changelog — Version history and roadmap

For developers

Forge itself is monadic. Every source file belongs to one tier. The repo is a worked example:

python -m pytest                     # 1291 passed, 2 skipped
forge doctor                         # Environment check
forge wire src/atomadic_forge        # Scan for violations (PASS)
forge certify . --fail-under 100     # Score and gate the repo (100/100)
forge status .                       # Quick health snapshot
forge commandsmith smoke             # Smoke-test all registered verbs

Before submitting a PR:

1. Run the test suite — must pass
2. Run ruff check src/ tests/ — code style check
3. Run forge wire src/atomadic_forge — import discipline
4. Update CHANGELOG.md

Status

Production-ready for architecture enforcement. Working, honest, self-eating.

• ✓ 1291 tests passing, 2 skipped
• ✓ 0 ruff errors — full lint sweep landed in v0.15.0
• ✓ 100/100 certify — forge scores itself on every CI run
• ✓ 0 wire violations — forge passes its own import-law scan
• ✓ On PyPI — pip install atomadic-forge (latest: v0.15.0)
• ✓ forge create / forge materialize — intent + seed repos → pip-installable package, deterministic, no LLM. From spaghetti to shippable in one command.
• ✓ MCP server — 66-tool surface (40 on the deployed Worker at forge.atomadic.tech/mcp, 66 in the local CLI / pip install); works with Cursor, Claude Code, Aider, Devin
• ✓ Hive primitives — hive_register / observe / propose / vote / result / list / deactivate / watch / needs-vote / recap for multi-agent consensus over append-only public artifacts
• ✓ AAAA-Nexus bridge — 7 LIVE primitives wired as MCP tools (nexus_identity_verify, nexus_federation_mint, nexus_authorize_action, nexus_sys_trust_gate, nexus_contract_verify, nexus_lineage_record, nexus_ratchet_register); wisdom + consensus auto-mirror at confidence ≥ 0.85
• ✓ Multi-agent safeguards — cost_circuit_breaker, dedup_engine, agent_hire_protocol, hierarchical_memory (MemGPT 4-tier)
• ✓ 8 LLM providers — auto, AAAA-Nexus, Anthropic, Gemini, OpenAI, OpenRouter, Ling-2.6-1T (free 1T-param frontier), Ollama (local)
• ✓ Ed25519 signing — forge certify --local-sign
• ✓ CycloneDX SBOM — forge sbom
• ✓ Compliance mappings — EU AI Act · NIST SR 11-7 · FDA PCCP · CMMC-AI
• ✓ Polyglot — Python + JavaScript + TypeScript, same 5-tier law
• ✗ Desktop GUI — moved to its own repo (atomadic-forge-tauri-studio)
• ✗ VS Code extension — moved to its own repo (atomadic-forge-vscode-ext)
• ✗ Cloudflare badge Worker — moved to its own repo (atomadic-forge-cloudflare-workers)
• ✗ Chain-of-custody notarization (future)
• ✗ Rust / Go tier classification (roadmap)

---

💰 Interested in investing? invest.atomadic.tech — learn about the Atomadic Technologies ecosystem.