ZenArc — AI-Native Task Manager

ZenArc replaces scattered TODO.md files with structured, AI-agent-friendly task files. It provides both an MCP server for Claude Code integration and a web dashboard for human browsing — with optional cloud sync for multi-device access.

Why ZenArc?

| | TODO.md | ZenArc | |---|---|---| | Cross-project view | ❌ Need to cat each file | ✅ Unified dashboard + MCP queries | | AI actionable | ❌ Unstructured markdown | ✅ Schema-validated YAML with tool hooks | | Status tracking | ✅ Checkboxes | ✅ Typed status + priority + assignee | | Context links | 🔶 Manual backticks | ✅ Structured files, urls, dependencies | | Git-friendly | ✅ Plain text | ✅ Human-readable YAML | | Agent attribution | ❌ Unknown who wrote what | ✅ created_by, assigned_to | | Mobile access | ❌ Desktop only | ✅ Optional Firebase sync |

Architecture

zenarc/
├── web/                    # Next.js 15 dashboard + workspace root
│   ├── app/                # Routes (dashboard, login, landing)
│   ├── components/         # React components (board, modals)
│   ├── lib/                # Firebase, sync server, utilities
│   ├── bin/zenarc.js       # CLI entry point (starts web dashboard)
│   └── packages/
│       ├── core/           # Task schema (Zod), YAML store, registry
│       └── sync-firebase/  # Optional Firestore sync layer

Data flow (Local Server Mode):

┌─────────────┐    stdio     ┌─────────────┐     ┌─────────────┐
│ Claude Code │◄────────────►│ zenarc-mcp  │────►│ Local YAML  │
└─────────────┘              └─────────────┘     └──────┬──────┘
                                                        │
                        ┌───────────────────────────────┘
                        │ (optional)
                        ▼
               ┌─────────────────┐
               │  Firebase       │
               │  Firestore      │
               └────────┬────────┘
                        │
                        ▼
               ┌─────────────────┐
               │  Web Dashboard  │
               │  (Next.js)      │
               └─────────────────┘

Data flow (Browser Mode):

┌─────────────────┐     File System Access API      ┌─────────────┐
│  Web Dashboard  │◄───────────────────────────────►│ Browser YAML│
│  (Next.js)      │                                   │  (disk)     │
└────────┬────────┘                                   └──────┬──────┘
         │                                                    │
         │              ┌─────────────────────────────────────┘
         │              │ (optional)
         ▼              ▼
┌─────────────────┐     ┌─────────────┐
│  Firebase       │◄───►│  Browser    │
│  Firestore      │      │  (IndexedDB │
└─────────────────┘      │  handles)   │
                         └─────────────┘

MCP works in both modes. zenarc-mcp is a separate CLI tool that reads/writes YAML directly via Node.js fs. It does not need the zenarc server running. Install it with npm install -g zenarc-mcp and configure it in Claude Code regardless of which dashboard mode you use.

Design principles:

• Local-first: Tasks are YAML files in each project's tasks/ directory. Works offline.
• MCP is local-only: The MCP server uses stdio transport. There is no HTTP/SSE/remote MCP endpoint.
• Optional cloud sync: Sign in with Google to sync tasks to Firestore for mobile access.
• Git-native: Tasks version alongside code. Review task changes in PRs.
• AI-first: Built for agents to read, write, and reason about work across projects. Claude Code integration via MCP.

Quick Start

ZenArc runs in two modes. Pick the one that fits your workflow:

| | Browser Mode | Local Server Mode | |---|---|---| | Install | None — open in browser | npm install -g @zenarc/zenarc | | Data storage | File System Access API (YAML in your repos) | Local filesystem (YAML in your repos) | | MCP / Claude Code | ✅ Install zenarc-mcp separately | ✅ Install zenarc-mcp separately | | Cloud sync | ✅ Firebase sync | ✅ Firebase sync | | Best for | Quick start, visual dashboard | CLI convenience bundle, always-on MCP |

Browser Mode (No Install)

1. Open the dashboard in your browser
2. Click Add Folder and select a project directory
3. Start managing tasks immediately

Your tasks are saved as YAML files in each project's .zenarc/tasks/ folder.

Browser support: Chrome and Edge (File System Access API required). Firefox/Safari are not supported for folder access.

Local Server Mode

npm install -g @zenarc/zenarc
zenarc              # Start on localhost:3000, auto-opens browser

Options:

zenarc --dev        # Development mode with hot reload
zenarc --build      # Build for production
zenarc --port 3001  # Custom port
zenarc --help

On first run, ZenArc auto-builds itself. Subsequent starts are instant.

Install

Option A: npm (recommended)

Requires access to the private @zenarc npm scope.

npm install -g @zenarc/zenarc

Option B: Source

git clone <private-repo-url> zenarc
cd zenarc/web
npm install
npm run build

Usage

Dashboard

• Browser mode: Open the deployed dashboard URL (or npm run dev at localhost:3000)
• Local mode: Open http://localhost:3000/dashboard after running zenarc

In both modes:

• No sign-in required for local usage. Your tasks live as YAML files on disk.
• Sign in with Google to enable cloud sync. A green cloud icon appears in the sidebar when sync is active.

Features

| Feature | Browser | Local | Description | |---------|---------|-------|-------------| | Kanban board | ✅ | ✅ | Drag-and-drop tasks across todo, in_progress, done, blocked, deferred | | Project sidebar | ✅ | ✅ | Switch between projects, see active task counts | | Filters | ✅ | ✅ | Filter by status and priority | | Cross-project board | ✅ | ✅ | Kanban view across all projects with drag-and-drop | | Task modals | ✅ | ✅ | Create and edit tasks with full metadata | | Project management | ✅ | ✅ | Add local projects (browser: "Add Folder", local: "Add Project") | | Cloud sync | ✅ | ✅ | Bidirectional sync between local YAML and Firestore | | MCP / Claude Code | ✅* | ✅ | Natural language task management via zenarc-mcp (install separately in browser mode) |

Cloud Sync (Optional)

Enable sync to access tasks from the mobile app or multiple computers.

How it works:

1. Desktop → Mobile: Every local change writes to YAML, then pushes to Firestore.
2. Mobile → Desktop: A background Firestore listener detects remote changes and writes them back to YAML (if the remote version is newer).

Setup:

1. Create a Firebase project
2. Enable Firestore Database and Authentication (Google provider)
3. Copy .env.example to .env.local and fill in your Firebase config
4. Sign in via the dashboard sidebar — sync starts automatically

MCP Server (Claude Code Integration)

Works in both Browser and Local Server modes. zenarc-mcp is a separate CLI tool that reads/writes YAML directly via Node.js fs. It does not need the zenarc server or the browser dashboard running. Install it with npm install -g zenarc-mcp and configure it in Claude Code regardless of which dashboard mode you use.

ZenArc's MCP server uses stdio transport. There is no HTTP, SSE, or remote MCP endpoint. Claude spawns zenarc-mcp as a subprocess. It reads and writes the same YAML files that the dashboard uses.

The web dashboard and MCP are independent interfaces to the same data. Both read from and write to the same local YAML files (and optional Firebase sync).

3-step setup:

npm install -g zenarc-mcp

Add to your Claude Code settings (~/.claude/settings.json or a project's .claude/settings.local.json):

{
  "mcpServers": {
    "zenarc": {
      "command": "zenarc-mcp"
    }
  }
}

Restart Claude Code. That's it — no server to run, no API keys, no ports to open. zenarc-mcp auto-initializes on first use.

First run: Ask Claude to scan your projects:

"Scan my projects in ~/dev"

Then use natural language for everything:

"List my critical tasks for loa-web"

"Mark the GA4 tracking task as done"

"Create a new high-priority task in codeyourreality to update the hero copy"

"Search for anything related to SEO across all projects"

MCP Tools Reference

| Tool | Description | |------|-------------| | zenarc_scan | Scan directories for ZenArc projects and sync to registry | | zenarc_list | List tasks with filters (status, priority, project, tag, assignee) | | zenarc_get | Get full task details by ID | | zenarc_create | Create a new task with structured metadata | | zenarc_update | Update task fields (status, priority, assignee, notes) | | zenarc_search | Keyword search across titles, tags, and notes | | zenarc_context_add | Link file paths or URLs to an existing task |

Why stdio (not HTTP)?

| stdio | HTTP/SSE | |-------|----------| | Zero config — Claude manages the process | Requires running a server, managing ports | | Works offline | Needs network | | No authentication needed | Needs API keys / OAuth | | Instant startup | Cold start latency | | Tasks live in your repo (git-native) | Data lives in the cloud |

If you need multi-device access, use Firebase sync (below) rather than a remote MCP endpoint. The dashboard reads from the same cloud data without requiring an HTTP MCP server.

Task File Format

Each task is a standalone YAML file in {project}/tasks/:

id: tm-20260602-a1b2c3d4
title: Fix GA4 '(not set)' page tracking
status: in_progress
priority: critical
project: loa-web
tags: [analytics, seo, bugfix]
created_at: "2026-05-10T09:00:00Z"
updated_at: "2026-05-18T14:30:00Z"
created_by: human
assigned_to: claude
context:
  files:
    - app/components/PageViewTracker.jsx
    - app/ClientLayout.js
  urls:
    - https://analytics.google.com/analytics/web/
  notes: >
    Fires manual page_view on App Router client-side navigations
    with 100ms delay for document.title to settle. Skips first
    render to avoid duplicating gtag('config') initial page_view.
dependencies: []

Schema Fields

| Field | Type | Description | |-------|------|-------------| | id | string | Unique ID (tm-YYYYMMDD-xxxxxxxx) | | title | string | Short task title | | status | enum | todo, in_progress, done, blocked, deferred | | priority | enum | critical, high, medium, low | | project | string | Project name (from registry) | | tags | string[] | Category tags | | created_at | ISO datetime | Creation timestamp | | updated_at | ISO datetime | Last update timestamp | | created_by | enum | human, claude, other-agent | | assigned_to | string? | Current assignee | | context.files | string[] | Related file paths | | context.urls | string[] | Related URLs | | context.notes | string | Freeform description | | dependencies | string[] | Task IDs this task depends on |

Project Registry

Projects are tracked in ~/.zenarc/projects.json:

[
  { "name": "loa-web", "path": "/Users/.../loa/loa-web", "format": "yaml" },
  { "name": "codeyourreality", "path": "/Users/.../codeyourreality", "format": "yaml" }
]

The registry is auto-populated during migration and zenarc_scan.

Development

Build all packages

npm run build

Run locally

npm run dev

Run migration

npm run migrate -- <project-name> <project-path>

Start MCP server manually

zenarc-mcp

This runs zenarc-mcp over stdio for local testing. It does not start an HTTP server — Claude Code/Desktop spawns this process automatically.

Publish to npm

node scripts/publish.js patch    # or minor / major

Tech Stack

• Core: TypeScript, Zod (schema validation), YAML (serialization)
• MCP Server: @modelcontextprotocol/sdk (stdio transport)
• Web Dashboard: Next.js 15, React 19, Tailwind CSS, App Router
• Sync: Firebase Firestore + Firebase Auth (Google sign-in)
• AI: Vercel AI SDK, OpenAI
• DnD: @dnd-kit
• Package Manager: npm workspaces

Roadmap

• [x] Task creation/editing UI in dashboard
• [x] MCP server for Claude Code integration
• [x] Drag-and-drop kanban columns
• [x] Firebase sync for multi-device access
• [x] CLI tool (zenarc) for quick launch
• [ ] Dependency graph visualization
• [ ] GitHub Actions integration (auto-create tasks from PR comments)
• [ ] Native mobile app (Flutter)
• [ ] Desktop notifications for due tasks