Full autonomy when you trust it. Full control when you don't.
Wallfacer is an autonomous engineering platform that works across multiple levels of abstraction. Start with a conversation when you're exploring an idea. Move to specs when the shape becomes clear. Track tasks when it's time to execute. Drop into code when you need precision. Agents operate at every level, and you decide how much freedom they get.
Open source. Runs locally. No IDE lock-in. No cloud dependency. Bring your own LLM provider.
 |
|---|
| Task board — coordinate parallel agent execution |
 |
|---|
| Plan mode — design before you build |
Every AI coding tool today pins you to one interaction mode. Chat-based tools are fast but lose structure at scale. Spec-driven tools add discipline but slow you down on day one. Task boards help you coordinate but don't understand your architecture. Wallfacer connects all of these into a continuous workflow.
Adaptive abstraction — Chat-centric for greenfield exploration, spec-centric for complex systems — a recursive tree of markdown specs that agents can read, iterate on, break down, and dispatch as tasks — task-centric for parallel execution, code-level for surgical edits. Move between levels as your project evolves.
Autonomy spectrum — Run the full loop autonomously (implement, test, commit, push) or step in at any point. Dial autonomy up or down per task, per spec, per project.
Spec as intermediate representation — Ideas don't go straight to code. They become structured specs that agents can reason about, iterate on, and implement against. Specs are versioned and reviewable.
Isolation by default — Per-task containers and git worktrees for safe parallel execution. Multiple agents work simultaneously without stepping on each other.
Operator visibility — Live logs, traces, timelines, diff review, and usage/cost tracking. Full audit trail from idea to deployed code.
Self-development — Wallfacer builds Wallfacer. Most recent capabilities were developed by the system itself.
Model flexibility — Works with Claude Code, Codex, and custom sandbox setups. Not locked to any single LLM provider.
Install:
curl -fsSL https://raw.githubusercontent.com/changkun/wallfacer/main/install.sh | shCheck prerequisites:
wallfacer doctorStart the server:
wallfacer runA browser window opens automatically. Add your Claude credential (OAuth token via claude setup-token, or API key from console.anthropic.com) in Settings. See Getting Started for the full setup walkthrough.
- Explore — Describe what you want to build in chat. Wallfacer helps you shape the idea.
- Specify — The idea becomes a structured spec. Iterate on it until the design is right.
- Execute — Specs break into tasks on a board. Agents implement, test, and commit in isolated sandboxes.
- Ship — Reviewed changes merge automatically. Auto-commit, auto-push, auto-build when you're ready.
flowchart LR
Idea([Idea]) --> Chat[Planning Chat]
Chat --> Spec[Root Spec]
Spec --> BreakDown[Break Down]
BreakDown --> Leaves[Leaf Specs]
Leaves --> Tasks[Dispatched Tasks]
Tasks --> Commits([Commits])
Plan mode is Wallfacer's design-time surface. A three-pane layout appears whenever any spec exists: file explorer on the left, focused spec view in the center, and planning chat on the right. When the specs tree is empty, plan mode collapses into a chat-first experience so you can start from an idea with zero scaffolding. Press P to toggle between the board and plan mode; E toggles the explorer, C toggles the chat, D dispatches, B breaks down.
graph LR
Chat[Chat<br/>exploratory] --> Spec[Spec<br/>structured design]
Spec --> Task[Task<br/>scoped execution]
Task --> Code[Code<br/>surgical edits]
Move left for more freedom and lower commitment; move right for more precision and higher commitment. Agents operate at every level, and autonomy dials up or down independently at each one.
Every spec carries one of six lifecycle states. Transitions are intentional — the planner drives them explicitly via slash commands or direct edits, and the tree UI surfaces the current state as a colored pill.
stateDiagram-v2
[*] --> vague
vague --> drafted
drafted --> validated
drafted --> stale
drafted --> archived
validated --> complete
validated --> stale
complete --> stale
complete --> archived
stale --> drafted
stale --> validated
stale --> archived
archived --> drafted
- vague — a seed idea, still being shaped in chat.
- drafted — structure and frontmatter in place; ready for review.
- validated — reviewed and accepted; leaf specs in this state are dispatchable.
- complete — all dispatched work landed; outcomes recorded.
- stale — the world moved; spec needs refresh before further work.
- archived — retired but preserved; can be revived back to drafted.
Planning chat accepts these slash commands. Type / to autocomplete.
| Command | Purpose |
|---|---|
/summarize |
Summarize the current thread or focused spec |
/create |
Create a new spec from the conversation |
/refine |
Tighten wording, scope, or structure of a spec |
/validate |
Check spec against the document model and mark validated |
/impact |
Analyze blast radius against existing specs and code |
/status |
Report progress across the spec tree |
/break-down |
Split a spec into child design specs or leaf tasks |
/review-breakdown |
Sanity-check a proposed breakdown |
/dispatch |
Dispatch validated leaf specs to the task board |
/review-impl |
Review an implementation against its spec |
/diff |
Compare a completed task against its source spec |
/wrapup |
Finalize a completed spec and record outcomes |
The agent may also emit /spec-new <path> as a scaffold directive — this is not a user command; it tells the server to create a new spec file at the given path with valid frontmatter defaults.
Read more: Designing Specs and Exploring Ideas.
Coordinate many agent tasks on a kanban board. Drag cards across the lifecycle, batch-create with dependency wiring, refine prompts before execution, and let autopilot promote backlog items as capacity opens. Each task runs in an isolated container with its own git worktree.
Design before you build. The three-pane plan view gives you an explorer tree (left), focused markdown view (center), and planning chat (right). Break large ideas into structured specs, validate dependencies, and dispatch leaf specs to the task board when the design is right.
Inspect what happened, when it happened, and why it happened before you accept any automated output. Every task produces a structured event timeline, diff against the default branch, and AI-generated oversight summary.
Track token usage and cost by task, activity, and turn so operations stay measurable as automation scales. Per-role breakdown (implementation, testing, refinement, oversight) shows exactly where budget goes.
- Execution engine: isolated containers, per-task git worktrees, worker container reuse, safe parallel runs, circuit breaker, resource limits, dependency caching
- Autonomous loop: prompt refinement, implementation, testing, auto-submit, autopilot promotion, auto-retry, cost/token budgets, failure categorization
- Spec workflow: structured design specs, five-state lifecycle, dependency DAG, recursive progress tracking, planning chat agent with slash commands
- Oversight layer: live logs, timelines, traces, diff review, usage/cost visibility, per-turn breakdown, task search, oversight summaries
- Repo operations: multi-workspace groups, branch switching, sync/rebase helpers, auto commit and push, task forking
- Development tools: file explorer with editor, interactive host terminal, prompt templates, system prompt customization
- Flexible runtime: Podman/Docker support, workspace-level AGENTS.md instructions, Claude + Codex backends, per-role sandbox routing
Development is organized into three parallel tracks with shared foundations. See specs/README.md for the full dependency graph and spec index.
Foundations (complete) — Sandbox backend interface, storage backend interface, container reuse, file explorer, host terminal, multi-workspace groups, Windows support.
Local Product — Desktop experience and developer workflow: spec coordination (document model, planning UX, drift detection), desktop app, file/image attachments, host mounts, oversight risk scoring, visual verification, live serve.
Cloud Platform — Multi-tenant hosted service: tenant filesystem, K8s sandbox backend, cloud infrastructure, multi-tenant control plane, tenant API.
Shared Design — Cross-track specs: authentication, agent abstraction, native sandboxes (Linux/macOS/Windows), overlay snapshots.
User Manual — start here for the full reading order.
| # | Guide | Topics |
|---|---|---|
| 1 | Getting Started | Installation, credentials, first run |
| 2 | The Autonomy Spectrum | Mental model: chat, spec, task, code |
| 3 | Exploring Ideas | Planning chat, slash commands, @mentions |
| 4 | Designing Specs | Spec mode, focused view, dependency minimap |
| 5 | Executing Tasks | Task board, lifecycle, dependencies, search |
| 6 | Automation & Control | Autopilot, auto-test, auto-submit, auto-retry |
| 7 | Oversight & Analytics | Oversight summaries, costs, timeline, logs |
| 8 | Workspaces & Git | Workspace management, git integration, branches |
| 9 | Refinement & Ideation | Prompt refinement, brainstorm agent |
| 10 | Configuration | Settings, env vars, sandboxes, CLI, shortcuts |
| 11 | Circuit Breakers | Fault isolation, self-healing automation |
Technical Internals — start here for implementation details and architecture.
| # | Reference | Topics |
|---|---|---|
| 1 | Architecture | System design, package map, handler organisation, end-to-end walkthrough |
| 2 | Data & Storage | Data models, persistence, event sourcing, spec document model |
| 3 | Task Lifecycle | State machine, turn loop, dependencies, failure categorization |
| 4 | Git Operations | Worktree lifecycle, commit pipeline, branch management |
| 5 | API & Transport | 97 HTTP routes, SSE, WebSocket terminal, middleware |
| 6 | Automation | Background watchers, autopilot, circuit breakers, ideation |
| 7 | Workspaces & Config | Workspace manager, sandboxes, templates, env config |
| 8 | Development Setup | Building, testing, make targets, release workflow |
Wallfacer started as a practical response to a repeated workflow: write a task prompt, run an agent, inspect output, and do it again. The bottleneck was not coding speed — it was coordination and visibility across many concurrent agent tasks. A task board became the control surface.
The first version was a Go server with a minimal web UI. Tasks moved from backlog to in progress, executed in isolated containers, and landed in done when complete. Git worktrees provided branch-level isolation so many tasks could run in parallel without collisions.
Then the system kept growing into its own gaps. The execution engine gained container reuse, circuit breakers, dependency caching, and multi-workspace groups. An autonomous loop handles prompt refinement, implementation, testing, auto-retry, and autopilot promotion. An oversight layer — live logs, timelines, traces, diffs, and per-turn cost breakdown — ensures every agent decision is auditable before results are accepted.
As the projects grew in complexity, raw task prompts became insufficient. Design specs emerged as the thinking layer between ideas and executable tasks — structured documents with lifecycle states, dependency graphs, and recursive progress tracking. A planning chat agent made specs conversational: explore an idea in chat, iterate on the design, break it into tasks, dispatch to the board.
The integrated development environment now includes a file explorer with editor, an interactive host terminal, system prompt customization, and prompt templates — all accessible from the browser.
Most of Wallfacer's recent capabilities were developed by Wallfacer itself, creating a compounding loop where the system continuously improves its own engineering process.