2dui

2dui turns plain JSON todo files into a browser UI that is easy for people to scan and easy for LLM agents to read, update, and reason about.

The project is built around a small 2dui / 2do CLI, a local HTTP server, and a Vite React app. Keep tasks close to the repository they describe, then launch a browser view when you want to inspect status, deadlines, tags, sources, and checklist steps without digging through raw JSON.

Live demo: https://2dui.pages.dev

Why

LLM coding agents are good at editing structured files, but todo state often lives in chat history, issue trackers, or prose notes that are hard to reconcile with the actual working tree. 2dui keeps project work in versionable JSON files and exposes the same data in two useful forms:

• a normalized JSON dataset for agents and scripts
• a browser UI for humans reviewing and steering the work

This makes todo files useful as a shared contract between a developer, an LLM assistant, and the project repository.

Features

• Discover todo.json files in a project tree.
• Validate todo files with Effect Schema and a generated JSON Schema.
• List, create, add, complete, reopen, remove, migrate, and validate tasks from the CLI.
• Serve a local browser UI over a project directory.
• Show open, blocked, overdue, completed, and all task views.
• Display priorities, due dates, tags, sources, descriptions, and checklist steps.
• Generate /data/todos.json as a normalized dataset for browser and agent use.
• Provide a reusable React TodoItem component in the workspace UI package.

Install

git clone https://github.com/anduimagui/2dui.git
cd 2dui
npm install
npm run build

The repository currently targets Node.js 20 or newer.

Quick Start

Create a todo file in any project:

node packages/cli/dist/index.js create /path/to/project/todo.json --title "Project Todos"

Add a task:

node packages/cli/dist/index.js add "Review auth flow" \
  --file /path/to/project/todo.json \
  --description "Check happy path and expired session behavior" \
  --priority 2 \
  --deadline 2026-08-15 \
  --tags frontend,auth

Open the browser UI:

node packages/cli/dist/index.js ui --path /path/to/project

The server binds to 127.0.0.1, serves the built Vite app, and generates /data/todos.json from the todo files under the selected project path.

CLI

node packages/cli/dist/index.js files --path /path/to/project
node packages/cli/dist/index.js list --path /path/to/project
node packages/cli/dist/index.js list --path /path/to/project --all
node packages/cli/dist/index.js list --path /path/to/project --format json
node packages/cli/dist/index.js validate --path /path/to/project
node packages/cli/dist/index.js schema --write packages/app/public/schemas/todo-schema.json
node packages/cli/dist/index.js migrate --path /path/to/project
node packages/cli/dist/index.js done "Review auth flow" --file /path/to/project/todo.json
node packages/cli/dist/index.js undone "Review auth flow" --file /path/to/project/todo.json
node packages/cli/dist/index.js remove "Review auth flow" --file /path/to/project/todo.json

The package also exposes 2dui and 2do bin names when installed from a built package.

JSON Format

A source todo file is intentionally explicit so agents can edit it with low ambiguity:

{
  "$schema": "https://raggle.co/todo-schema.json",
  "version": 2,
  "id": "todo",
  "title": "Project Todos",
  "people": [],
  "projects": [],
  "cycles": [],
  "milestones": [],
  "components": [],
  "areas": [],
  "integrations": [],
  "customFields": [],
  "automations": [],
  "tasks": [
    {
      "id": "todo:0",
      "key": "TODO-1",
      "index": 0,
      "rank": "0001",
      "name": "Review auth flow",
      "description": "Check happy path and expired session behavior.",
      "type": "task",
      "status": "todo",
      "resolution": null,
      "done": false,
      "priority": 2,
      "deadline": "2026-08-15",
      "overdue": false,
      "reporterId": null,
      "assigneeIds": [],
      "estimate": null,
      "projectIds": [],
      "cycleId": null,
      "milestoneIds": [],
      "componentIds": [],
      "areaIds": [],
      "parentId": null,
      "relations": [],
      "links": [],
      "acceptanceCriteria": [],
      "steps": [
        {
          "id": "review-auth-flow:happy-path",
          "text": "Confirm happy path",
          "done": true
        },
        {
          "id": "review-auth-flow:expired-session",
          "text": "Check expired session behavior",
          "done": false
        }
      ],
      "comments": [],
      "decisions": [],
      "createdAt": null,
      "updatedAt": null,
      "startedAt": null,
      "completedAt": null,
      "canceledAt": null,
      "tags": ["frontend", "auth"],
      "customFields": [],
      "reminder": null,
      "source": {
        "id": "todo",
        "title": "Project Todos"
      }
    }
  ]
}

Use status: "blocked" for blocked tasks. The UI treats status as the authoritative task state.

Browser UI

The browser app is a local operational view rather than a hosted task backend. It reads the generated dataset, groups work by source file, and supports:

• status filters for open, blocked, late, done, and all tasks
• search across task names, descriptions, tags, sources, and checklist steps
• source-file filtering
• task detail routes
• copyable task context for handing work back to an LLM assistant

For app development with Vite HMR:

npm run dev

For a production-like local preview:

npm run build
npm --workspace @2dui/app run preview

LLM Agent Workflow

Recommended pattern for agent-assisted projects:

1. Keep a todo.json file at the project root or inside relevant subprojects.
2. Ask the agent to inspect and update tasks as part of implementation work.
3. Use 2dui validate --path . before relying on the file.
4. Launch 2dui ui --path . to review the work visually.
5. Use 2dui list --format json --path . when another tool needs normalized machine-readable task state.

Because the source files are normal JSON, they can be reviewed in pull requests, diffed with code changes, and kept close to the implementation they describe.

Install the global agent skill from this checkout with:

./install-skills.sh

The installer copies the single 2dui skill into ${AGENTS_HOME:-$HOME/.agents}/skills/2dui.

Development

npm install
npm run build
npm run typecheck
npm run lint

Workspace layout:

• packages/cli - Node CLI, todo discovery, schema generation, and local server.
• packages/app - Vite React browser UI.
• packages/ui - reusable React UI components.
• .agents/skills/2dui - the single installable agent skill source.
• packages/app/public/data/todos.json - static demo dataset for the deployed UI.
• todo.json - source-format example todo file.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for setup, checks, and contribution guidelines.

License

MIT - see LICENSE.