Atomadic Forge

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

🔗 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 or JavaScript / TypeScript 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.

Languages: Python (.py), JavaScript (.js / .mjs / .cjs / .jsx), TypeScript (.ts / .tsx). Cloudflare Workers, Node back-ends, and mixed Python+JS repositories all classify in a single pass — no Node dependency, 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/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 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)

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.6.1
forge doctor      # environment check

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               # 937 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"]
    }
  }
}

24 tools exposed: recon · wire · certify · enforce · audit_list · auto_plan · auto_step · auto_apply · context_pack · preflight_change · score_patch · select_tests · rollback_plan · explain_repo · adapt_plan · compose_tools · load_policy · why_did_this_change · what_failed_last_time · list_recipes · get_recipe · worktree_status · trust_gate_response · exported_api_check

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

Observability & compliance

Agent & LLM loops

Composition & tooling

Targeted workflows

# Targeted: just see what's in a repo
forge recon ./repo

# Targeted: pick specific symbols
forge cherry ./repo --pick infer_tier --pick CherryPicker

# Targeted: merge two repos with conflict resolution
forge cherry ./repo-a --pick all
forge finalize ./repo-a ./out --apply --on-conflict rename

# Specialty: surface compositions across your own catalog
forge emergent scan

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 53 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

Pricing

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

👑 Atomadic Lifetime Founder — $999 — first 25 only. One key. Forever. Lifetime Forge Standard Pro + Forge Deluxe (when launched) + AAAA-Nexus + every future Atomadic product. See forge.atomadic.tech/pricing.

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 13+ 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                     # 937 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 36+ 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.

• ✓ 944 tests passing, 2 skipped
• ✓ 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.6.1)
• ✓ MCP server — full tool surface; works with Cursor, Claude Code, Aider, Devin
• ✓ 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.