AGINEAR

The Problem with Project Management Tools

Linear is a great tool. But for solo developers and small teams shipping with AI agents, it's overkill. The UI has a steep learning curve, there's a ton of overhead just to track a few tasks, and the AI agent story is rough — your agent has to go through Linear's MCP server, which means API calls, authentication, and massive token consumption just to read a task list. Every query eats context window for what should be a trivial operation.

Meanwhile, your project already has a natural home for structured text: markdown files in the repo. A todo.md sitting next to your source code is version-controlled, greppable, editable in any text editor, and visible in every git diff. An AI agent can read and edit a markdown file in its sleep — no API, no auth, no token bloat. The only problem is that bare markdown has no tooling — no Kanban view, no filtering, no structured interface for agents that want something cleaner than regex.

AGINEAR (agents + Linear) fixes that. It treats todo.md and roadmap.md as the single source of truth, then wraps them with a CLI, a web GUI, and an MCP server — all powered by a lossless markdown engine that preserves every byte of formatting you add.

How It Works

The core of AGINEAR is a custom line-by-line CST (Concrete Syntax Tree) parser. No markdown AST library — I wrote a parser that tracks every blank line, every comment, every bit of prose you add between tasks. The invariant is strict: serialize(parse(input)) === input. Your formatting survives every operation.

Sections are ## headings, which become Kanban columns in the web GUI. Tasks are standard checkbox syntax (- [ ] and - [x]). Inline metadata like @assignee #tag !priority ^due-date gets parsed out of the task title and becomes structured data. Subtasks nest up to three levels deep with two-space indentation. Notes are indented plain text under a task.

The roadmap file follows a similar pattern — milestones are ## headings with status: and progress: metadata, a prose description, and task items.

Three Interfaces, One Truth

CLI — aginear list, aginear add, aginear done, aginear move. Everything you need from the terminal. Tasks resolve by position number, ID prefix, or fuzzy title match.

Web GUI — aginear serve launches a React SPA with a drag-and-drop Kanban board. Click a task to edit its properties. Toggle completion via checkbox. There's a roadmap timeline view with progress bars. Live updates over WebSocket when files change on disk — so if you edit todo.md in your editor, the board updates instantly.

MCP Server — This is the killer feature. AGINEAR exposes your task list to AI coding agents via the Model Context Protocol. Claude Code, Claude Desktop, Cursor — any MCP-compatible tool can list tasks, add new ones, mark them done, and move them between columns. The agent doesn't need to parse markdown or guess at file format. It gets structured JSON through well-defined tools.

If you're using Claude Code, the setup is a three-line JSON config in .claude/settings.json. After that, your AI agent can check what needs to be done, pick up a task, and mark it complete when it ships the code. It's the workflow I describe in structuring projects for AI agents — but with actual tool support instead of hoping the agent reads your markdown correctly.

Key Design Decisions

No markdown AST library. Libraries like remark or unified are built for rendering markdown to HTML. They normalize formatting, strip comments, and reflow text. That's exactly what you don't want when the markdown file is the database. The custom CST parser preserves the original text byte-for-byte.

No state outside markdown files. The .devplan/config.json stores preferences (column names, port, tag colors), not task data. If you delete the config, nothing breaks — AGINEAR uses sensible defaults. Your tasks are always in todo.md, always human-readable, always portable.

Tiny install. Everything bundles into ~94 KB gzipped via tsup and Vite, with third-party deps installed by npm. The CLI, MCP server, and web GUI all ship in one package. npx aginear init gets you running in under a second.

Monorepo with shared core. The project is split into four packages — core (CST parser, mutator, serializer), cli (Commander + Chalk), mcp (MCP SDK with stdio transport), and web (Express + React SPA). The parser is shared across all three interfaces, so behavior is identical everywhere.

The MCP Angle

I've built a few MCP servers now, and the pattern keeps proving itself. MCP turns AI agents from text generators into tool users. For project management, that means your agent doesn't have to be told "look at todo.md and figure out what to work on." It can call get_todos, get a structured list, pick a task, and call complete_task when it's done. That's a fundamentally different workflow than pasting file contents into a prompt.

If you care about building projects that AI agents can actually work on, having a structured task interface is table stakes. AGINEAR is my answer to that.

Getting Started

cd your-repo
npx aginear init        # Creates todo.md, roadmap.md, .devplan/config.json
npx aginear list        # View tasks
npx aginear serve       # Launch web GUI at http://localhost:4040

The whole thing is open source on GitHub. 89 tests across the core and MCP packages. MIT licensed.