@zenarc/zenarc

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  │────►│ ~/.zenarc/projects/   │
└─────────────┘              └─────────────┘     │ Local YAML            │
                                                 └──────┬────────────────┘
                                                        │
                        ┌───────────────────────────────┘
                        │ (optional)
                        ▼
               ┌─────────────────┐
               │  Firebase       │
               │  Firestore      │
               └────────┬────────┘
                        │
                        ▼
               ┌─────────────────┐
               │  Web Dashboard  │
               │  (Next.js)      │
               └─────────────────┘

Data flow (Browser Mode):

┌─────────────────┐     File System Access API      ┌───────────────────────┐
│  Web Dashboard  │◄───────────────────────────────►│ ~/.zenarc/projects/   │
│  (Next.js)      │                                   │ Browser YAML (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 ~/.zenarc/projects/{name}/tasks/. 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-friendly: Source repos stay clean; task data is stored outside your repositories.
• 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	npm install -g @zenarc/zenarc, then zenarc init	npm install -g @zenarc/zenarc
Data storage	~/.zenarc/projects/{name}/	~/.zenarc/projects/{name}/
MCP / Claude Code	✅ Install zenarc-mcp separately	✅ Install zenarc-mcp separately
Cloud sync	✅ Firebase sync	✅ Firebase sync
Best for	Visual dashboard without a running local server	CLI convenience bundle, always-on MCP

Browser Mode

Browser mode uses the File System Access API to read and write the same YAML files as Local Server mode. The centralized ~/.zenarc/ folder must be created first with the CLI.

npm install -g @zenarc/zenarc
zenarc init

Then open the dashboard in your browser, click Open ~/.zenarc/, and select your ~/.zenarc/ directory. Click Add Folder and select a project source directory.

Your tasks are saved as YAML files in ~/.zenarc/projects/{projectName}/tasks/.

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 init                       # Create the centralized ~/.zenarc/ folder (one-time)
zenarc                            # Start on localhost:3000, auto-opens browser

Then click Add Project in the dashboard and select a source folder. You can also register a project from the terminal:

zenarc create <project-name> <source-path>

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:

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

Setup:

• Create a Firebase project
• Enable Firestore Database and Authentication (Google provider)
• Copy .env.example to .env.local and fill in your Firebase config
• 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 ~/.zenarc/projects/{projectName}/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

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

• Task creation/editing UI in dashboard
• MCP server for Claude Code integration
• Drag-and-drop kanban columns
• Firebase sync for multi-device access
• 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