AGINEAR

Markdown-native project management. todo.md and roadmap.md are the single source of truth. CLI, Web GUI, and MCP server — all powered by a lossless markdown engine.

Quick Start

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

Setup

Requires Node.js >= 18.

cd your-repo
npx aginear init

This creates:

your-repo/
├── todo.md                  # Your tasks (editable by hand or via CLI/GUI)
├── roadmap.md               # Your milestones
├── .devplan/
│   └── config.json          # Per-repo configuration
└── .gitignore               # .devplan/ entry appended automatically

Both markdown files are yours to edit directly — AGINEAR preserves every byte of formatting you add (blank lines, prose, comments).

Install Globally (optional)

npm install -g aginear

Markdown Format

todo.md

# My Project

## Backlog
- [ ] Set up database @aditya #backend !high ^2025-06-01
- [ ] Write API docs #docs

## In Progress
- [ ] Build auth flow @aditya #backend !critical
  - [x] Design token schema
  - [ ] Implement JWT validation
    - [ ] Add RS256 support
  - [ ] Write auth middleware
  Notes about the auth flow.

## Done
- [x] Initialize repo

Sections are ## headings — they become Kanban columns in the GUI.

Tasks are - [ ] (incomplete) or - [x] (complete) list items.

Subtasks are indented 2 spaces under their parent. Up to 3 levels deep.

Notes are indented plain text under a task (not a list item).

Inline metadata can appear anywhere in the task title:

| Token | Meaning | Example | |---|---|---| | @name | Assignee | @aditya | | #tag | Tag (multiple allowed) | #backend #api | | !priority | Priority | !critical, !high, !medium, !low | | ^YYYY-MM-DD | Due date | ^2025-06-01 |

roadmap.md

# Product Roadmap

## MVP Launch
status: in-progress
progress: 60%

Core features for initial release.

- [x] User authentication
- [x] Basic CRUD
- [ ] Payment integration

## V2 Features
status: planned

- [ ] Analytics dashboard
- [ ] Export to CSV

Milestones are ## headings.

Metadata are key: value lines directly under the heading:

• status: — planned, in-progress, completed, blocked
• progress: — 0% to 100%

Description is any prose text between the metadata and the task items.

CLI Reference

Task Management

# List all tasks
aginear list
aginear list --section "In Progress"
aginear list --tag backend
aginear list --assignee aditya

# Add a task
aginear add "Implement search"
aginear add "Build dashboard" --section "In Progress" --assign aditya --priority high --tag frontend --tag ui --due 2025-06-01

# Mark complete / uncomplete
aginear done "search"              # Fuzzy matches title
aginear done 3                     # By displayed list number
aginear done 0e0023                # By ID prefix (shown in list output)

# Move between sections
aginear move "search" --to "In Progress"

# Edit properties
aginear edit "search" --title "New title" --assign bob --priority medium --due 2025-07-01

# Remove
aginear remove "search"

Task Identification

All commands that take a <query> argument resolve tasks with this strategy:

1. Numeric — matches by position in the displayed list (aginear done 3)
2. 6-8 hex chars — matches by task ID prefix (aginear done 0e0023)
3. Otherwise — case-insensitive substring match on task titles (aginear done "auth flow")

If multiple tasks match, you'll see a disambiguation list.

Roadmap Management

# View roadmap
aginear roadmap

# Add milestone
aginear roadmap add "V3 Features" --status planned

# Update milestone
aginear roadmap update "MVP" --status completed --progress 100

Web GUI

aginear serve              # http://localhost:4040
aginear serve --port 8080  # Custom port

Features:

• Kanban board with drag-and-drop between columns
• Click any task to edit title, assignee, priority, tags, due date
• Toggle task completion via checkbox
• Roadmap timeline view with progress bars and status badges
• Live updates via WebSocket when files change on disk

Initialize

aginear init

Creates todo.md, roadmap.md, and .devplan/config.json with defaults. Skips any file that already exists. Appends .devplan/ to .gitignore.

MCP Server

AGINEAR includes an MCP server so AI coding agents (Claude Desktop, Cursor, Claude Code, etc.) can read and modify your project tasks.

Setup for Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "aginear": {
      "command": "npx",
      "args": ["aginear", "mcp"],
      "cwd": "/absolute/path/to/your/repo"
    }
  }
}

Setup for Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "aginear": {
      "command": "npx",
      "args": ["aginear", "mcp", "--cwd", "."]
    }
  }
}

Setup for Claude Code

Add to .claude/settings.json in your project:

{
  "mcpServers": {
    "aginear": {
      "command": "npx",
      "args": ["aginear", "mcp", "--cwd", "."]
    }
  }
}

Available Tools

| Tool | Description | Input | |---|---|---| | get_todos | Get all tasks, optionally filtered | { section?, tag?, assignee?, priority? } | | add_task | Add a new task | { title, section?, assignee?, tags?, priority?, due? } | | update_task | Update an existing task | { search, updates: { title?, assignee?, priority?, tags?, due?, completed? } } | | move_task | Move task to a different section | { search, to_section } | | complete_task | Mark a task as complete | { search } | | remove_task | Remove a task | { search } | | get_roadmap | Get the full roadmap | {} | | update_milestone | Update milestone status/progress | { search, status?, progress? } |

The search parameter matches by ID prefix or case-insensitive title substring.

Configuration

.devplan/config.json is optional. AGINEAR uses sensible defaults if it's missing.

{
  "files": {
    "todo": "./todo.md",
    "roadmap": "./roadmap.md"
  },
  "gui": {
    "port": 4040
  },
  "columns": ["Backlog", "In Progress", "Review", "Done"],
  "tags": {}
}

| Key | Default | Description | |---|---|---| | files.todo | ./todo.md | Path to the todo file (relative to config dir) | | files.roadmap | ./roadmap.md | Path to the roadmap file (relative to config dir) | | gui.port | 4040 | Port for the web GUI | | columns | ["Backlog", "In Progress", "Review", "Done"] | Kanban column names | | tags | {} | Tag name to hex color mapping |

Config is resolved by walking up from cwd looking for .devplan/config.json (like .git). File paths in the config are resolved relative to the directory containing .devplan/.

REST API

When running aginear serve, these endpoints are available:

Todos

| Method | Endpoint | Body | Description | |---|---|---|---| | GET | /api/todos | -- | Full todo document as JSON | | POST | /api/todos/tasks | { title, section?, assignee?, tags?, priority?, due? } | Add task | | PATCH | /api/todos/tasks/:id | { title?, assignee?, tags?, priority?, dueDate?, completed? } | Update task | | DELETE | /api/todos/tasks/:id | -- | Remove task | | POST | /api/todos/tasks/:id/move | { section, position? } | Move task | | POST | /api/todos/tasks/:id/complete | -- | Toggle completion |

Roadmap

| Method | Endpoint | Body | Description | |---|---|---|---| | GET | /api/roadmap | -- | Full roadmap document as JSON | | PATCH | /api/roadmap/milestones/:id | { status?, progress? } | Update milestone |

WebSocket

Connect to ws://localhost:4040 (same port). The server broadcasts these messages when files change on disk:

{ "type": "todos_updated", "data": { "title": "...", "sections": [...] } }
{ "type": "roadmap_updated", "data": { "title": "...", "milestones": [...] } }

Development

git clone https://github.com/Legorobotdude/AGINEAR.git
cd AGINEAR
pnpm install
pnpm -r build
pnpm -r test       # 89 tests across core + mcp

Project Structure

packages/
  core/     # Shared CST parser, mutator, serializer (lossless round-tripping)
  cli/      # CLI commands (commander + chalk)
  mcp/      # MCP server (@modelcontextprotocol/sdk, stdio transport)
  web/      # Express server + React SPA (Vite + Tailwind + @dnd-kit)

Publishing a New Version

1. Bump the version in two places:

   • publish-package.json — the "version" field (this is what npm sees)
   • packages/cli/src/index.ts — the .version() call in Commander (this is what aginear --version prints)

2. Build, pack, and verify:

   pnpm run publish:build
   pnpm run publish:pack       # creates aginear-<version>.tgz in repo root

3. Publish:

   cd dist && npm publish --access public

The publish:build script does the following:

• Builds all workspace packages (pnpm -r build)
• Bundles cli, mcp, and server entry points into dist/ via tsup, inlining @devplan/* workspace deps while keeping third-party deps external
• Copies the web client assets, publish-package.json, README, and LICENSE into dist/
• Prepends the Node shebang to dist/cli.js

Key Design Decisions

• No markdown AST library -- Custom line-by-line CST parser that preserves every byte. serialize(parse(input)) === input.
• No state outside markdown files -- The .md files are the database. Config is for preferences only.
• Tiny install -- Everything bundles into ~94 KB (gzipped) via tsup/Vite with third-party deps installed by npm.

License

MIT