# v0.0.1

## What is Wallfacer?

Wallfacer is a Kanban task runner for [Claude Code](https://claude.ai/code). It provides a web-based Kanban board where you create task cards, drag them to "In Progress" to trigger Claude Code execution inside isolated sandbox containers, and inspect results when done — all from your browser.

The name comes from the [Wallfacer Project](https://en.wikipedia.org/wiki/The_Three-Body_Problem_(novel)#Wallfacer_Project) in Liu Cixin's *The Three-Body Problem*: independent thinkers given full autonomy to work on hard problems in isolation. Each task card is a wallfacer — given a prompt and left to work autonomously in its own sandbox, reporting back when done or when it needs guidance.

![Overview](https://raw.githubusercontent.com/changkun/wallfacer/main/assets/overview-plain.png)

## Why build this?

Working with Claude Code follows a repetitive loop: write a task → run Claude → review output → provide feedback → repeat. This is a natural Kanban workflow. Wallfacer automates this loop:

- **Parallel execution** — Run multiple Claude Code tasks concurrently without conflicts
- **Git isolation** — Each task gets its own worktree and branch; your main branch stays clean
- **Hands-off operation** — Drag a card to "In Progress" and walk away; come back to review the diff
- **Human-in-the-loop** — When Claude needs clarification, the card moves to "Waiting"; submit feedback to resume

## Features

- **Visual Kanban board** with drag-and-drop (Backlog → In Progress → Waiting/Done/Failed/Cancelled)
- **Isolated sandbox execution** — each task runs in an ephemeral Podman/Docker container
- **Git worktree isolation** — every task gets its own branch and worktree for conflict-free concurrency
- **Human-in-the-loop feedback** — tasks pause in "Waiting" when Claude needs input; submit feedback to resume
- **Auto commit & push** — completed changes are automatically committed, rebased, and merged to the default branch
- **Live log streaming** — real-time container output via Server-Sent Events (SSE)
- **Full event timeline** — immutable audit trail of state changes, outputs, feedback, and errors per task
- **Usage tracking** — input/output tokens, cache hits, and cost (USD) accumulated per task
- **Workspace CLAUDE.md** — per-workspace instructions managed from the UI, mounted into every container
- **Multi-workspace support** — mount multiple project directories; Claude can work across all of them
- **Diff viewer** — inspect exactly what changed before accepting results
- **Session continuity** — multi-turn conversations preserved across feedback rounds via `--resume`
- **Auto-continue** — tasks hitting token limits automatically continue in the same session
- **Conflict resolution** — if git rebase fails, Claude is invoked to resolve conflicts automatically
- **Crash recovery** — on restart, orphaned in-progress tasks are recovered to "Failed" with full history
- **Container monitoring** — inspect running sandbox containers from the settings panel

## Architecture

```
Browser (Vanilla JS + Tailwind + Sortable.js)
    │ SSE
    ▼
Go Server (stdlib net/http, no framework)
    │ os/exec
    ▼
Ephemeral Sandbox Containers (Podman/Docker)
    │
    ▼
Git Worktrees (~/.wallfacer/worktrees/)
```

### Design choices

| Choice | Rationale |
|---|---|
| **No web framework** | stdlib `net/http` with Go 1.22+ pattern routing is sufficient |
| **No frontend framework** | Vanilla JS + Tailwind keeps the UI lightweight and dependency-free |
| **No database** | Filesystem persistence with atomic writes (temp file + rename) is crash-safe and human-readable |
| **Git worktrees** | True isolation — unlimited concurrent tasks without git conflicts |
| **Event sourcing** | Immutable audit trail; enables crash recovery and replay |
| **SSE over WebSocket** | Simpler server-side; one-directional push is all the UI needs |
| **Ephemeral containers** | No state leaks between tasks; each run starts completely clean |

### Minimal dependencies

The Go server imports only `github.com/google/uuid`. No ORMs, no web frameworks, no database drivers.

## How it's built

Built over 171 commits in 6 days (Feb 16–21, 2026). The project is self-referential: after the initial scaffolding, most features were implemented by Wallfacer itself — create a task card describing the feature, drag to In Progress, and let Claude build it in a sandbox.

**Backend** (~5000 LOC Go): stdlib HTTP server, container orchestration via `os/exec`, per-task filesystem persistence with event sourcing, git worktree management, structured logging.

**Frontend** (~2000 LOC JS): vanilla JavaScript modules for state management, API calls, drag-and-drop, markdown rendering, live log streaming, and theme switching. Styled with Tailwind CSS.

**Sandbox image**: Ubuntu 24.04 with Go 1.25, Node.js 22, Python 3, Claude Code CLI, and standard development tools. Multi-arch (amd64 + arm64).

## Quick start

```bash
# 1. Get OAuth token
claude setup-token

# 2. Configure
mkdir -p ~/.wallfacer
echo "CLAUDE_CODE_OAUTH_TOKEN=<your-token>" > ~/.wallfacer/.env

# 3. Build and run
go build -o wallfacer .
wallfacer run ~/your-project
```

Browser opens at http://localhost:8080. Create a task, drag it to "In Progress", and watch Claude work.

## Task lifecycle

```
Backlog → In Progress → Done
              ↓ ↑
              ├→ Waiting ──feedback──→ In Progress
              │           ──mark done→ Done
              └→ Failed ──resume────→ In Progress
                        ──retry─────→ Backlog
```

## Prerequisites

- Go 1.25+
- Podman or Docker
- Claude Pro or Max subscription

## Full documentation

See the [docs/](https://github.com/changkun/wallfacer/tree/main/docs) directory for detailed architecture, task lifecycle, git worktree design, and API reference.
