ForgeKit
ForgeKit is a personal agent-operations forge — you wire up AI providers, equip
agents with the right skills for a job, run them under operator-gated runtime policy,
and keep every result in a durable memory. It is not another chatbot: it orchestrates
multiple providers, agents and tools to carry a real task to a bounded finish.
forge (a smithy — heat metal, hammer it to shape) + kit (a set of tools).
What ForgeKit is
A monorepo with two cooperating apps:
forgekit-console — the operator TUI (Claude-Code-style). You configure the brain,
switch runtime modes, resolve work, and read honest status.engineering-agent (yule) — an always-on, role-based engineering runtime (Discord
gateway + member bots, SQLite job queue, Obsidian vault mirror).
Everything is provider-neutral (Claude / Codex / Gemini / Ollama and any openai-compatible
or enterprise endpoint sit behind one contract) and operator-gated (approval / budget /
safe-class boundaries are real, not decorative).
Core concepts
| Concept | One line | Code |
|---|
| ForgeKit | the whole platform / execution environment | this repo |
| Hephaistos | the skill-forging core — turns a request into an equip plan (agent + skills + loadout + weapons + work packet) | forgekit_console/hephaistos/ |
| Nexus | the external knowledge source (areas / patterns / snippets / troubleshooting) Hephaistos reads (never copies) | read path: hephaistos/nexus_read.py |
| Armory | the catalog of Skills / Loadouts / Weapons Hephaistos forges from | hephaistos/armory.py |
| Work Packet | a structured, executable unit (goal / scope / forbidden / commands / verify / approval / evidence) | hephaistos/models.py |
| Runtime Mode | the operator posture (Shift+Tab) that actually changes routing / budget / approval | policy/runtime_mode.py |
Mine → library → smith: Nexus is the mine/library, ForgeKit is the forge, Hephaistos is the smith.
Current reality (honest)
Status is one of working / partial / planned / blocked — see the matrices
in docs/operator-surfaces.md and docs/evidence-map.md.
| Capability | Status | Surface | Evidence |
|---|
| Multi-provider config + routing (no implicit ollama) | working | submit path, /mode | examples/runtime-teeth/ |
| Vendor-native usage ledger (live vs estimate) | working | /usage | examples/usage/ |
| Hephaistos resolve (request → equip plan) | working | /resolve /hephaistos /skills /loadout | examples/hephaistos/ |
| Armory breadth (7 categories, 25 skills, 8 loadouts) | working | /resolve | test_armory_breadth |
| Nexus read path (bounded, restricted-aware) | partial | /resolve nexus line | examples/hephaistos/nexus-read-foundation/ |
| Always-on bounded daemon + safe-class autopilot | working | forgekit runtime serve | examples/runtime/, examples/autopilot/ |
Provider /provider console config (set primary / list / doctor) | working | /provider | test_provider_surface |
| Nexus live repo connection | planned (not_connected until FORGEKIT_NEXUS_ROOT set) | — | — |
| Live Figma / YouTube / Google / Instagram | planned seam (never live in this tree) | /sources shows planned | — |
No fake-live. Anything not wired is shown as planned / not_connected / blocked /
restricted / unsupported_in_console, never as if it works.
Quick start
pip install -e '.[console]' # console extra (textual + image render)
forgekit # open the operator console TUI
yule --help # the engineering runtime CLI (runtime/harness/doctor/…)
First run with no provider configured → the console reports setup-required and free-text
submit is held. You choose the brain — ForgeKit does not silently use a reachable
local Ollama (implicit local fallback is OFF by default).
Provider / setup / doctor / mode
