Detailed Analysis
Solocode.plan is a lightweight, native macOS kanban application built by an independent developer to solve a specific friction point in AI-assisted software development: keeping project planning artifacts visible and accessible to Claude Code, Anthropic's terminal-based agentic coding tool. Rather than relying on external task managers or cloud services, the tool stores all plan data directly inside the project repository as plain files — a `.solocode-plan.json` at the root for card metadata and individual `.md` files per card under a `.solocode-plan/` directory. This "plan-as-code" architecture means the entire planning history, including decisions, post-mortems, and research notes, travels with every `git clone` and remains fully within the scope of what an AI agent operating on the local filesystem can read and manipulate.
The integration mechanism is deliberately minimal and architecturally notable. Rather than building a Model Context Protocol (MCP) server, exposing an API, or embedding any AI logic within the app itself, solocode.plan injects a structured instruction block into the project's `CLAUDE.md` file — the conventional location Claude Code uses to load per-project context and behavioral rules. This block communicates the JSON schema, valid column and category identifiers, atomic write discipline (temp-file-then-rename to avoid partial reads by the file watcher), and a context economy rule instructing Claude not to preemptively load all markdown note files on every interaction. The result is a clean separation of concerns: the macOS app acts as a dumb file renderer with a fast file-watcher-driven UI, while Claude Code provides all reasoning and execution. The two systems communicate entirely through the filesystem.
The context economy rule deserves particular attention as a demonstration of practical prompt engineering at the project level. Without it, a sufficiently large board could cause Claude Code to ingest dozens of markdown files on every request, rapidly consuming context window capacity and degrading response quality. By encoding this constraint directly in `CLAUDE.md`, the developer effectively programs a retrieval discipline into the agent's behavior — opening individual card notes only on explicit user request. This is a concrete, working example of the broader challenge in agentic AI systems of managing what information gets loaded when, a problem that grows more acute as project memory accumulates over time.
Solocode.plan sits within a rapidly expanding ecosystem of kanban-style tools purpose-built around Claude Code workflows, including langwatch/kanban-code (a SwiftUI-native macOS session manager), the Claude Code Kanban Automator (which adds automated task execution and retry loops), and Vibe Kanban (a web-based parallel agent orchestrator). What distinguishes solocode.plan is its philosophical stance: it avoids automation of AI execution entirely, positioning itself instead as a persistent project memory layer. Cards are described explicitly as living documents rather than disposable to-do items, accumulating decisions and post-mortems over a project's lifecycle. This reframes the kanban board from an ephemeral task queue into a durable, version-controlled knowledge base that complements rather than duplicates what an AI coding assistant can infer from code alone.
The broader significance of solocode.plan lies in what it reveals about the emerging design space for human-AI collaborative development tooling. As Claude Code and similar agentic tools become standard components of solo and small-team workflows, developers are discovering that the conventional separation between "project management" and "development environment" breaks down. When an AI agent operates directly on the repository, any artifact that exists outside the repo is effectively invisible to it. The CLAUDE.md convention — pioneered by Anthropic as a project-scoped instruction mechanism — is proving to be a flexible integration surface that third-party tools can write to without requiring any formal plugin architecture. Solocode.plan's success with this approach, using nothing more than a JSON schema and a handful of behavioral rules, suggests that the CLAUDE.md file may become a de facto extension point for an entire category of local-first, agent-aware developer tooling.
Read original article →