Codex-powered task orchestration for long-running software delivery.
Mycelium turns an implementation plan into explicit tasks, runs them in isolated workers (Docker by default), validates outcomes, and can resume after interruptions.
- Autopilot flow: interview -> planning artifacts -> task generation -> run.
- Task runner: per-task workspaces + task branches, parallel scheduling, checkpoint commits, resume.
- Safety rails: per-task manifests (declared reads/writes + locks) with
off|warn|blockenforcement. - Validation: repo doctor + optional LLM validators (test/style/architecture/doctor) that can gate merges.
- Observability: JSONL logs, optional SQLite index for fast queries, failure digests, UI visualizer.
- Repo navigation: control graph commands (
mycelium cg ...) for ownership, deps, blast radius, symbols.
- Node 20+
- Git repo (Mycelium discovers the repo root via
.git) - Docker (recommended), or use
--local-workerto run workers on the host - API key for your chosen provider:
CODEX_API_KEY(Codex)OPENAI_API_KEY(OpenAI)ANTHROPIC_API_KEY(Anthropic)
npm install
npm run build
npm linkmycelium initThis scaffolds:
.mycelium/config.yaml(project config).mycelium/doctor.sh(integration doctor stub; update it for your repo).mycelium/planning/002-implementation/implementation-plan.md(starter stub).mycelium/tasks/(generated task specs/manifests).mycelium/.gitignore(keeps Mycelium artifacts out of git)
Edit <repo>/.mycelium/config.yaml:
- Set
doctorto a real verification command (usually./.mycelium/doctor.sh). - Configure
planner+workerprovider/models. - Set
bootstrapfor worker setup (example:npm ci).
Option A: autopilot (end-to-end)
mycelium autopilot --max-parallel 2Option B: plan + run
mycelium plan --input .mycelium/planning/002-implementation/implementation-plan.md
mycelium run --max-parallel 2Resume after Ctrl+C or a crash:
mycelium resume --run-id <id>Check status:
mycelium status --run-id <id>Start the localhost-only UI server for a run:
mycelium ui --run-id <id>run and resume can also launch the UI via config/flags (--ui, --ui-port, --ui-open).
logs requires a project name (most other commands default it from the repo folder name).
mycelium logs --project <project> --run-id <id> --use-index
mycelium logs timeline --project <project> --run-id <id> --use-index
mycelium logs failures --project <project> --run-id <id>
mycelium logs summarize --project <project> --run-id <id> --task 001 --llmmycelium cg build
mycelium cg owner src/index.ts
mycelium cg deps <component-id>
mycelium cg symbols find "buildCli"See docs/control-plane/repo-navigation-tools.md for the full surface.
- Repo-scoped config and task artifacts live under
<repo>/.mycelium/. - Runtime state/logs/workspaces live under
<MYCELIUM_HOME>/(default:<repo_path>/.mycelium).
npm install
npm test
npm run typecheck
npm run lint
npm run format:check
npm run buildPackaging smoke test:
npm run pack:smokeWorker image build:
npm run docker:build-worker- Architecture overview:
docs/architecture/overview.md - ADRs:
docs/architecture/adr/ - Ops runbooks:
docs/ops/ - Spec traceability:
docs/spec-traceability.md
src/app/: use-cases and orchestration wiringsrc/core/: shared logic and state (CLI/UI-free)src/cli/: CLI adapter and command wiringsrc/ui/: HTTP/UI adapter + static assetssrc/validators/: validator adapters (test/style/doctor/architecture)src/control-plane/: control graph + policy toolingsrc/docker/: Docker worker adaptersrc/git/: VCS adaptersrc/llm/: LLM client adaptersworker/: task execution loop
Apache-2.0 (see LICENSE).