{"id":48776747,"url":"https://github.com/yafitzdev/fitz-forge","last_synced_at":"2026-04-17T02:03:27.734Z","repository":{"id":339262050,"uuid":"1160293985","full_name":"yafitzdev/fitz-forge","owner":"yafitzdev","description":"Overnight AI architectural planning on local hardware. Queue a job. Go to sleep. Wake up to a plan.","archived":false,"fork":false,"pushed_at":"2026-04-13T12:33:23.000Z","size":2380,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T13:36:57.627Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yafitzdev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap/artifact-closure-principle.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-17T19:14:17.000Z","updated_at":"2026-04-13T12:35:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yafitzdev/fitz-forge","commit_stats":null,"previous_names":["yafitzdev/fitz-graveyard","yafitzdev/fitz-forge"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/yafitzdev/fitz-forge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yafitzdev%2Ffitz-forge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yafitzdev%2Ffitz-forge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yafitzdev%2Ffitz-forge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yafitzdev%2Ffitz-forge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yafitzdev","download_url":"https://codeload.github.com/yafitzdev/fitz-forge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yafitzdev%2Ffitz-forge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31911846,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-16T18:22:33.417Z","status":"online","status_checked_at":"2026-04-17T02:00:06.879Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-13T13:05:04.721Z","updated_at":"2026-04-17T02:03:27.716Z","avatar_url":"https://github.com/yafitzdev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\n\n\u003cdiv align=\"center\"\u003e\n\n# fitz-forge\n\n### Architectural coding planning harness for local LLMs\n\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![PyPI version](https://badge.fury.io/py/fitz-forge.svg)](https://pypi.org/project/fitz-forge/)\n[![Tests](https://github.com/yafitzdev/fitz-forge/actions/workflows/test.yml/badge.svg)](https://github.com/yafitzdev/fitz-forge/actions/workflows/test.yml)\n[![Version](https://img.shields.io/badge/version-0.6.2-green.svg)](CHANGELOG.md)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\n[The Problem](#the-problem) • [The Insight](#the-insight-) • [Why fitz-forge?](#why-fitz-forge) • [Benchmarks](#benchmarks) • [How It Works](#how-it-works) • [Docs](docs/features/) • [GitHub](https://github.com/yafitzdev/fitz-forge)\n\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" colspan=\"2\"\u003e\n      \u003cpre\u003e\u003cstrong\u003eTask: \"Add WebSocket support to the chat API\"\u003c/strong\u003e\n(Given a real codebase with FastAPI routes, Pydantic schemas, and an existing REST chat endpoint.)\u003c/pre\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cstrong\u003e❌ Raw local LLM (no harness)\u003c/strong\u003e\n\u003cpre\u003e\n\"Add a WebSocket endpoint.\n Use the websockets library.\n Create a new file for handlers.\n Add authentication middleware.\"\n\u003c/pre\u003e\n\u003cem\u003eGeneric advice. No file paths. No awareness\nof existing code. Hallucinated library choice.\nWould break the existing architecture.\u003c/em\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"50%\"\u003e\n      \u003cstrong\u003e🔨 fitz-forge (same model, same hardware)\u003c/strong\u003e\n\u003cpre\u003e\nPhase 1: Extend ChatRouter in api/routes/chat.py\n  - Add ws_chat() using existing ChatEngine\n  - Reuse AuthMiddleware.verify_token()\n  - Test: pytest tests/api/test_chat_ws.py\n\nPhase 2: Adapt MessageSchema in schemas/chat.py\n  - Add ws_message field (matches existing\n    ChatMessage.content structure)\n  - Verify: pydantic model_validate()\n\u003c/pre\u003e\n\u003cem\u003eReal files. Real methods. Phased roadmap\nwith verification commands. Grounded in\nthe actual codebase.\u003c/em\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n→ Same model, same hardware. The difference is the harness: `fitz-forge` reads your codebase, reasons in stages, self-critiques, \nand extracts structured output that a small model can actually produce reliably.\n\n\u003c/div\u003e\n\n--- \n\n### Where to start 🚀\n\n\u003e [!IMPORTANT]\n\u003e Requires [Ollama](https://ollama.com), [LM Studio](https://lmstudio.ai), or [llama.cpp](https://github.com/ggerganov/llama.cpp) \n\u003e with a loaded model. Also needs [fitz-sage](https://github.com/yafitzdev/fitz-sage) for code retrieval.\n\n```bash\npip install fitz-forge\n\nfitz plan \"Add OAuth2 authentication with Google and GitHub providers\"\n```\n\nThat's it. Your plan runs overnight on local hardware.\n\n---\n\n### About\n\nI built `fitz-forge` because the best AI coding tools are dangerously dependent on subsidized API pricing. \nClaude Code costs $100/month *today* — heavily subsidized. When those subsidies shrink, the planning phase alone \n(understanding a codebase, reasoning about architecture, producing a structured plan) could cost more than the subscription. \n`fitz-forge` moves that expensive planning phase onto hardware you already own. No API costs. No data leaving your network. \nAnd as local models improve, your plans improve for free.\n\nNo LangChain. No LlamaIndex. Every layer written from scratch, with code retrieval powered by [fitz-sage](https://github.com/yafitzdev/fitz-sage).\n\n~20k lines of Python. 970+ tests. Built by Yan Fitzner ([LinkedIn](https://www.linkedin.com/in/yan-fitzner/), [GitHub](https://github.com/yafitzdev)).\n\n![fitz-forge llm_with_harness](https://raw.githubusercontent.com/yafitzdev/fitz-forge/main/docs/assets/llm_with_harness.jpg)\n\n---\n\n### Why `fitz-forge`?\n\n**Cut your Opus bill — plan locally, implement with Sonnet 💸**\n\u003e Agentic planning is the most expensive part of the process, and it's where LLMs struggle the most. `fitz-forge` \n\u003e produces a markdown artifact you hand to Sonnet for implementation. The expensive tokens never hit your API budget.\n\n**Dumb local models produce smart plans 🧠**\n\u003e The pipeline breaks the task into atomic decisions, resolves each against relevant files, then narrates the committed \n\u003e decisions into a plan. Suddenly a local model can produce plans that would overwhelm it in a single prompt.\n\n**Runs on whatever hardware you've got 🖥️**\n\u003e Consumer GPU? Models like `Qwen3.6-35-a3b` or `Gemma4-26B-A4b` do the whole pipeline. CPU-only box or tiny VRAM? Run a medium model at 10 tok/s \n\u003e overnight. Tokens-per-second stops mattering when you're sleeping.\n\n**Drops into Claude Code or Codex via CLI and MCP 🔌**\n\u003e Expose `fitz-forge` as an MCP server (`fitz serve`) and it becomes a tool inside Claude Code, or any MCP-capable client.\n\u003e Same principle as with CLI. Tell Claude to create a plan using `fitz-forge`, and it does the heavy lifting locally while you wait.\n\n**Any codebase, any language 🌐**\n\u003e Python, Go, Rust — the retrieval layer indexes by file structure and imports, and the grounding layer validates generated \n\u003e artifacts against whatever the codebase actually contains.\n\n**Queue a job. Go to sleep. Relax. Let it run overnight. 🌙**\n\u003e Every stage produces checkpoints. Power outage at minute 15 of a 20-minute run? `fitz retry \u003cid\u003e` picks up from the \n\u003e last completed stage.\n\n**Fully local execution possible 🏠**\n\u003e Ollama, LM Studio, or llama.cpp. No API keys required to start.\n\n---\n\n### Benchmarks\n\nTBD\n\n---\n\n### How It Works\n\nA 10-stage pipeline that decomposes architectural planning into small, focused LLM calls interleaved with deterministic \nAST work. Retrieval + implementation check feed a decision-based reasoning core (decompose → resolve → synthesize), then \nartifacts are generated, closure-checked, and grounded against the real codebase before the plan is written.\n\n\u003cbr\u003e\n\n```\n     USER PROMPT\n          │\n          ▼\n┌─────────────────────────────────────────┐\n│ 1. Agent Context Gathering    [6-8 LLM] │  retrieval + compression\n├─────────────────────────────────────────┤\n│ 2. Implementation Check       [1 LLM]   │  already built?\n├─────────────────────────────────────────┤\n│ 3. Call Graph Extraction      [0 · AST] │  deterministic\n├─────────────────────────────────────────┤\n│ 4. Decision Decomposition     [2-4 LLM] │  adaptive best-of-N\n├─────────────────────────────────────────┤\n│ 5. Decision Resolution        [10-15]   │  1 call per decision\n├─────────────────────────────────────────┤\n│ 6. Synthesis                  [~15 LLM] │  reasoning + 13 extractions\n├─────────────────────────────────────────┤\n│ 7. Artifact Generation        [3-8 LLM] │  per-artifact + closure checks\n├─────────────────────────────────────────┤\n│ 8. Grounding Validation       [0-5 LLM] │  AST + repair\n├─────────────────────────────────────────┤\n│ 9. Coherence Check            [1 LLM]   │  cross-stage sanity\n├─────────────────────────────────────────┤\n│ 10. Render + Write            [0]       │  markdown to disk\n└─────────────────────────────────────────┘\n          │\n          ▼\n    ~/.fitz-forge/plans/plan_\u003cid\u003e.md\n\nTotal: ~40-60 LLM calls · ~7-9 min on RTX 5090\n```\n\n| # | Stage | Docs |\n|---|-------|------|\n| 1 | Agent Context Gathering | [01_agent-context-gathering.md](docs/features/pipeline/01_agent-context-gathering.md) |\n| 2 | Implementation Check | [02_implementation-check.md](docs/features/pipeline/02_implementation-check.md) |\n| 3 | Call Graph Extraction | [03_call-graph-extraction.md](docs/features/pipeline/03_call-graph-extraction.md) |\n| 4 | Decision Decomposition | [04_decision-decomposition.md](docs/features/pipeline/04_decision-decomposition.md) |\n| 5 | Decision Resolution | [05_decision-resolution.md](docs/features/pipeline/05_decision-resolution.md) |\n| 6 | Synthesis | [06_synthesis.md](docs/features/pipeline/06_synthesis.md) |\n| 7 | Artifact Generation | [07_artifact-generation.md](docs/features/pipeline/07_artifact-generation.md) |\n| 8 | Grounding Validation | [08_grounding-validation.md](docs/features/pipeline/08_grounding-validation.md) |\n| 9 | Coherence Check | [09_coherence-check.md](docs/features/pipeline/09_coherence-check.md) |\n| 10 | Render + Write | — |\n\n\u003cbr\u003e\n\n\u003e [!NOTE]\n\u003e The pipeline decomposes a problem that would overwhelm a small model into many small LLM calls it can handle reliably. \n\u003e Each per-field JSON extraction is under 2000 chars — small enough for a 3B quantized model to produce valid output. \n\u003e Deterministic AST work (call graph, grounding check) carries the structural load so LLMs only do what LLMs are good at.\n\nFull pipeline docs: **[docs/features/](docs/features/)** — detailed docs covering every stage and infrastructure component.\n\n---\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\u003cstrong\u003e📦 Quick Start\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```bash\n# Install\npip install fitz-forge\n\n# Queue a job\nfitz plan \"Build a plugin system for data transformations\"\n\n# Start the background worker\nfitz run\n\n# Check on it\nfitz status 1\n\n# Read the plan\nfitz get 1\n```\n\n**Optional extras:**\n```bash\npip install \"fitz-forge[api-review]\"    # Anthropic API review pass\npip install \"fitz-forge[lm-studio]\"    # LM Studio provider (openai SDK)\npip install \"fitz-forge[dev]\"          # pytest, build tools\n```\n\n**Prerequisites:**\n- Python 3.10+\n- [Ollama](https://ollama.com), [LM Studio](https://lmstudio.ai), or [llama.cpp](https://github.com/ggerganov/llama.cpp) with a loaded model\n- [fitz-sage](https://github.com/yafitzdev/fitz-sage) for code retrieval\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\u003cstrong\u003e📦 CLI Reference\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```bash\nfitz plan \"description\"   # Queue a planning job\nfitz run                  # Start background worker (Ctrl+C to stop)\nfitz list                 # Show all jobs\nfitz status \u003cid\u003e          # Check progress\nfitz get \u003cid\u003e             # Print completed plan as markdown\nfitz retry \u003cid\u003e           # Re-queue failed/interrupted job\nfitz confirm \u003cid\u003e         # Approve optional API review\nfitz cancel \u003cid\u003e          # Skip API review, finalize plan\nfitz serve                # Start MCP server\n```\n\n**Job lifecycle:**\n```\nQUEUED -\u003e RUNNING -\u003e COMPLETE\n                  -\u003e AWAITING_REVIEW -\u003e QUEUED (confirm) / COMPLETE (cancel)\n                  -\u003e FAILED / INTERRUPTED (both retryable)\n```\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\u003cstrong\u003e📦 MCP Server\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\nPlug into Claude Code or Claude Desktop:\n\n```json\n{\n  \"mcpServers\": {\n    \"fitz-forge\": {\n      \"command\": \"fitz\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n**MCP Tools:**\n\n| Tool | Description |\n|------|-------------|\n| `create_plan` | Queue a new planning job |\n| `check_status` | Check job progress |\n| `get_plan` | Retrieve completed plan |\n| `list_plans` | List all planning jobs |\n| `retry_job` | Retry a failed job |\n| `confirm_review` | Approve API review after seeing cost |\n| `cancel_review` | Skip API review, finalize plan |\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\u003cstrong\u003e📦 Configuration\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\nAuto-created on first run:\n\n| Platform | Path |\n|----------|------|\n| Windows | `%LOCALAPPDATA%\\fitz-forge\\fitz-forge\\config.yaml` |\n| macOS | `~/Library/Application Support/fitz-forge/config.yaml` |\n| Linux | `~/.config/fitz-forge/config.yaml` |\n\nDatabase (`jobs.db`) lives in the same directory.\n\n```yaml\n# LLM provider: \"ollama\", \"lm_studio\", or \"llama_cpp\"\nprovider: lm_studio\n\nlm_studio:\n  base_url: http://localhost:1234/v1\n  model: qwen3-coder-30b-a3b-instruct    # single model for retrieval + reasoning\n  smart_model: null                        # null = use model for all tiers\n  fast_model: null                         # null = use model for all tiers\n  timeout: 600\n  context_length: 65536                    # split reasoning auto-enables below 32768\n\nollama:\n  base_url: http://localhost:11434\n  model: qwen2.5-coder-next:80b-instruct\n  fallback_model: qwen2.5-coder-next:32b-instruct  # OOM fallback (null to disable)\n  timeout: 300\n  memory_threshold: 80.0  # RAM % threshold to abort\n\nllama_cpp:\n  server_path: /path/to/llama-server\n  models_dir: /path/to/models\n  port: 8012\n  fast_model:\n    path: model.gguf\n    context_size: 65536\n    gpu_layers: -1\n    flash_attention: true\n    cache_type_k: q8_0\n    cache_type_v: q8_0\n\nagent:\n  enabled: true\n  max_file_bytes: 50000\n  max_seed_files: 50    # files available via inspect_files/read_file tools\n  source_dir: null      # null = cwd at runtime\n\nconfidence:\n  default_threshold: 0.7\n  security_threshold: 0.9\n\nanthropic:\n  api_key: null  # null = API review disabled\n  model: claude-sonnet-4-5-20250929\n\noutput:\n  plans_dir: .fitz-forge/plans\n  verbosity: normal\n```\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\u003cstrong\u003e📦 Architecture\u003c/strong\u003e → \u003ca href=\"docs/ARCHITECTURE.md\"\u003eFull Architecture Guide\u003c/a\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```\nCLI (typer)   --\u003e tools/ --\u003e SQLiteJobStore \u003c-- BackgroundWorker --\u003e PlanningPipeline\nMCP (fastmcp) --\u003e tools/ --\u003e SQLiteJobStore\n```\n\n```\nfitz_forge/\n├── cli.py                     # Typer CLI (9 commands)\n├── server.py                  # FastMCP server + lifecycle\n├── __main__.py                # python -m fitz_forge (MCP stdio)\n├── tools/                     # Service layer\n├── models/                    # JobStore ABC, SQLiteJobStore, JobRecord\n├── background/                # BackgroundWorker, signal handling\n├── llm/                       # LLM clients (Ollama, LM Studio, llama.cpp), retry\n├── planning/\n│   ├── pipeline/stages/       # 3 stages (split or combined) + orchestrator + checkpoints\n│   ├── agent/                 # Code retrieval bridge to fitz-sage\n│   ├── prompts/               # Externalized .txt prompt templates\n│   └── confidence/            # Per-section confidence scoring\n├── api_review/                # Anthropic review client + cost calculator\n├── config/                    # Pydantic schema + YAML loader\n└── validation/                # Input sanitization\n```\n\n\u003c/details\u003e\n\n---\n\n\u003cdetails\u003e\n\n\u003csummary\u003e\u003cstrong\u003e📦 Development\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```bash\ngit clone https://github.com/yafitzdev/fitz-forge.git\ncd fitz-forge\npip install -e \".[dev]\"  # editable install for development\npytest  # 970+ tests\n\n# Lint\nruff check fitz_forge/\nruff format --check fitz_forge/ tests/\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full development guide and [examples/](examples/) for usage examples.\n\n**Benchmark factory** for A/B testing pipeline changes:\n```bash\n# Retrieval benchmarks (~12s/run)\npython -m benchmarks.plan_factory retrieval --runs 10 --source-dir ../your-project\n\n# Reasoning benchmarks with fixed retrieval\npython -m benchmarks.plan_factory reasoning --runs 5 --source-dir ../your-project \\\n  --context-file benchmarks/ideal_context.json --split --max-seeds 5\n```\n\n\u003c/details\u003e\n\n---\n\n### License\n\nMIT\n\n---\n\n### Links\n\n- [GitHub](https://github.com/yafitzdev/fitz-forge)\n- [PyPI](https://pypi.org/project/fitz-forge/)\n- [Changelog](CHANGELOG.md)\n- [Architecture](docs/ARCHITECTURE.md)\n- [Feature Docs](docs/features/) — 17 detailed docs covering every pipeline stage and infrastructure component\n- [Configuration Reference](docs/CONFIG.md) — every config field explained\n- [Troubleshooting](docs/TROUBLESHOOTING.md) — GPU issues, Windows quirks, pipeline debugging\n- [Contributing](CONTRIBUTING.md)\n- [Examples](examples/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyafitzdev%2Ffitz-forge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyafitzdev%2Ffitz-forge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyafitzdev%2Ffitz-forge/lists"}