CodePlans

Coordinate and track changes across your software architecture.

CodePlans is an open-source engineering planning tool that helps teams manage coordinated code changes across complex systems. It maps demand (work items: features, bugs, tech debt) onto delivery (code plans and tasks) across your architecture (products and assets), giving teams a shared view of what's changing, where, and why. Code owners and architects review plans and specs before the work starts, My Work tells each person what needs them, and the Product Wiki brings specs, decisions, and delivery records together into a searchable view of your system.

→ Beta signup: codeplans.ai · Docs: sylonzero.github.io/CodePlans

Plan & deliver → Code plans, work items and releases	Assets → The Atlas, asset record and history
Specs & Wiki → Versioned specs, diffs and the Product Wiki	Reviews → Plan and spec reviews, anchored discussion
My Work → An inbox built from your responsibilities	Notifications → Bell, email (Resend) and Slack

Screenshots come from the demo workspace (pnpm db:seed-demo). Take the full tour →

Modern engineering teams struggle with change coordination across distributed codebases. Tickets track individual tasks but miss the bigger picture; architecture docs go stale; migrations and refactors span multiple services with no shared source of truth.

CodePlans sits between your issue tracker and your architecture diagram:

• Products group your system's components under a planning boundary
• Assets represent individual components (apps, services, libraries, datastores, platforms) with health and tech debt tracking
• Work Items are the demand side — features, bugs, UX issues, and tech debt items — linked many-to-many to the plans that address them (natively, or mirrored from GitHub/GitLab)
• Code Plans coordinate related changes across assets with owners, assignees, deadlines, per-asset branch/PR tracking, and progress
• Tasks are the individual units of work tied to a plan and optionally scoped to a specific asset
• Responsibilities (engineering managers, architects, code owners) decide who reviews what and what shows up in each person's My Work; org roles still decide what they're allowed to do

Read the story behind every asset. Open Wiki in its own browser tab to move from the product architecture to a service's specs, design decisions, active plans, known issues, and delivery history.

• Find the detail: search document bodies and technical identifiers, then narrow by asset, type, status, area, or date.
• Read comfortably: full Markdown documents with tables, code, task lists, section links, and related content alongside.
• Follow the evidence: see authors, edit times, spec revisions, and capability receipts without confusing planned work with shipped versions.

Wiki screenshots use a synthetic Atlas demo workspace. See asset pages and search in the visual tour →

Run pnpm db:migrate before deploying to apply the additive SQLite/PostgreSQL attribution migration. See the wiki guide.

Stop a misdirected change before anyone spends effort on it. Code owners review a plan before work starts, not the PR after it's done.

• Responsibilities, not permissions: name engineering managers and architects per product, and code owners per asset. Reviewers are suggested from them.
• Reviews pinned to a version: approving v3 says nothing about v4. Revising a spec or plan marks earlier approvals outdated and tells the people involved. Products choose Open (optional reviews) or Guided (suggested reviewers, confirmation before activating unapproved work).
• Anchored discussion: comment on selected spec text, ask questions, suggest changes, @mention teammates and resolve threads.
• My Work: an inbox of what needs you (reviews, triage, mentions, evidence gaps), what you're carrying, and what changed, with Developer, Code owner, Architect and Eng manager lenses.
• Notifications: a bell in the app, plus email through Resend and a Slack incoming webhook. Admins choose events per channel; people turn off their own email and mute products or assets.

See the reviews guide, My Work guide and notifications guide.

CodePlans has two independent configuration axes that control how an instance behaves.

Self-hosted team (recommended default):

HOST_MODE=team
REGISTRATION=closed

Hosted SaaS with open signup:

HOST_MODE=saas
REGISTRATION=open

Closed beta / waitlist:

HOST_MODE=saas
REGISTRATION=invite

Commercial/hosted-only features are built as an optional private module the app loads at startup, never as forked or hidden code in this repo. See the enterprise extensions guide.

• Node.js 20+
• pnpm (npm install -g pnpm)

# 1. Clone the repo
git clone https://github.com/SylonZero/CodePlans.git
cd CodePlans

# 2. Install dependencies
pnpm install

# 3. Configure environment
cp .env.example .env.local
# .env.example defaults to HOST_MODE=team, REGISTRATION=closed, SQLite — no changes needed

# 4. Run migrations and create the admin account
pnpm db:migrate
pnpm db:seed

# 5. Start the dev server
pnpm dev

Open http://localhost:3000 and sign in with:

Change your password in Settings → Security after first login.

Want realistic demo data? Run pnpm db:seed-demo after pnpm db:seed to populate the workspace with products, assets, plans, and tasks. All demo accounts use password Password1! — see Demo accounts below.

Deploying to a server? Set AUTH_URL=https://your-server-domain (or http://ip:port) in .env.local. Auth.js requires this in production to construct correct callback URLs — without it, login redirects will fail.
If running the dev server on a remote machine, also set ALLOWED_DEV_ORIGINS=your.server.ip.

# Set these variables in .env.local
HOST_MODE=saas
REGISTRATION=open
AUTH_PROVIDER=supabase
DB_PROVIDER=postgres
DATABASE_URL=postgresql://...
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-publishable-key
SUPABASE_SECRET_KEY=your-service-role-key

Then run pnpm db:migrate and pnpm dev.

CodePlans/
├── app/                        # Next.js App Router
│   ├── (auth)/                 # Login & signup pages
│   └── (dashboard)/            # Protected app pages
│       ├── page.tsx            # Dashboard
│       ├── products/           # Product list + detail
│       ├── plans/              # Code Plans list + detail
│       ├── tasks/              # Task management
│       ├── team/               # Team & org management
│       ├── analytics/          # Analytics
│       └── settings/           # User settings
├── components/
│   ├── app-shell.tsx           # Sidebar + header layout
│   ├── dashboard/              # Dashboard widgets
│   └── ui/                     # Radix/shadcn primitives
├── lib/
│   ├── auth/                   # Pluggable auth adapters
│   ├── db/
│   │   ├── schema.sqlite.ts    # SQLite schema (Drizzle)
│   │   ├── schema.pg.ts        # Postgres schema (Drizzle)
│   │   ├── queries.ts          # Read queries
│   │   ├── mutations.ts        # Write operations
│   │   ├── migrations/         # SQL migration files
│   │   └── seed.ts             # Development seed data
│   ├── config.ts               # Environment config
│   └── types.ts                # Shared TypeScript types
├── tests/
│   ├── helpers/db.ts           # Test fixtures & helpers
│   └── lib/                    # Query & mutation tests
└── docs/                       # Technical documentation

The core data model:

users
  └── organizationMembers ──→ organizations
        └── products
              ├── assets
              │     └── assetDependencies
              └── codePlans
                    └── tasks

Both SQLite and Postgres schemas are maintained in parallel under lib/db/. Migrations live in lib/db/migrations/{sqlite,postgres}/.

pnpm test              # run all tests (416 tests across 41 files)
pnpm test:watch        # watch mode
pnpm test:coverage     # with coverage report

Tests use an in-memory SQLite database and run in isolated forked processes.

pnpm db:generate       # generate migrations from schema changes
pnpm db:migrate        # apply migrations
pnpm db:push           # push schema directly (dev only)
pnpm db:studio         # open Drizzle Studio
pnpm db:seed           # create admin account + default workspace
pnpm db:seed-demo      # populate with realistic multi-user demo data

The seed scripts respect three optional env vars for the admin account:

SEED_ADMIN_EMAIL=admin@example.com   # default
SEED_ADMIN_PASSWORD=Password1!       # default
SEED_ADMIN_NAME=Admin                # default
SEED_ORG_NAME="My Workspace"         # default

After running pnpm db:seed-demo, five accounts are available:

Every password is Password1!. The demo workspace includes 3 products, 15 assets, 11 code plans and ~65 tasks, plus versioned specs, open reviews, anchored discussion and two evidence gaps, so each role's My Work has something in it. Sign in as Mike for a code owner's view and Alex for an engineering manager's.

Contributions are welcome. To get started:

1. Fork the repo and create a feature branch
2. Make your changes — the SQLite local mode requires no cloud setup
3. Add or update tests in tests/
4. Open a pull request with a clear description

Please keep PRs focused. Bug fixes, test coverage improvements, and documentation updates are especially appreciated.

Specs are native, product-owned documents stored as GFM Markdown. Create or link one from an asset's Specs tab or the plan/work-item panels, edit with version checks, and supersede a document when the approach changes. Graduation pins the linked spec version to the delivered capability; Asset Record shows current intent and delivery coverage separately.

Existing git URLs remain readable citations. Apply pnpm db:migrate, then preview their import with pnpm specs:migrate --product=<product-id> --dry-run; review the report before using --apply. Both SQLite and PostgreSQL have additive Drizzle migrations. Imports preserve source URLs, deduplicate within each product, and never overwrite later native edits on reruns.

See the specs guide for editing, MCP, and migration details, or the monorepo modeling guide for choosing asset boundaries.

CodePlans ships an MCP server at /api/mcp/mcp (Streamable HTTP, bearer-token auth). Create an API key in Settings → API Keys — the settings page shows these snippets with your host and freshly minted key pre-filled, for Claude Code, Cursor, Codex, GitHub Copilot, and Antigravity.

Claude Code (user scope — available in every project):

claude mcp add --scope user --transport http codeplans http://localhost:3000/api/mcp/mcp \
  --header "Authorization: Bearer cpk_your_key"

Cursor — add to ~/.cursor/mcp.json (or .cursor/mcp.json per project), then enable under Settings → MCP:

{
  "mcpServers": {
    "codeplans": {
      "url": "http://localhost:3000/api/mcp/mcp",
      "headers": { "Authorization": "Bearer cpk_your_key" }
    }
  }
}

Codex CLI — reads the bearer token from an environment variable rather than storing it in ~/.codex/config.toml directly:

export CODEPLANS_API_KEY="cpk_your_key"
codex mcp add codeplans \
  --url http://localhost:3000/api/mcp/mcp \
  --bearer-token-env-var CODEPLANS_API_KEY

GitHub Copilot CLI:

copilot mcp add --transport http codeplans http://localhost:3000/api/mcp/mcp \
  --header "Authorization: Bearer cpk_your_key"

In VS Code's Copilot Chat instead, add the same URL/header under a "servers" entry in .vscode/mcp.json with "type": "http".

Antigravity — add to ~/.gemini/config/mcp_config.json (note the field is serverUrl, not url), then reload MCP servers from the agent panel:

{
  "mcpServers": {
    "codeplans": {
      "serverUrl": "http://localhost:3000/api/mcp/mcp",
      "headers": { "Authorization": "Bearer cpk_your_key" }
    }
  }
}

Your agent can then read specs, plans, work items, and tech debt and (with a write-scope key) create, revise, supersede, and link specs, model products, assets, and dependencies, manage plans end-to-end (create, target assets, activate/complete), file work items, manage tasks, and record branch/PR status on plan assets. Keys act as your user, so org access rules and mirrored-field protections apply unchanged. See docs/specs/mcp-server-spec.md.

• Product & asset CRUD forms — shipped in v0.1.5 (side panels & quick modals)
• Code Plan create/edit flows — shipped in v0.1.5
• Task create/edit panel + inline status updates — shipped in v0.1.5
• Team invite flow (invite, change role, remove)
• v0.2.0 — Schema foundations & single-team cleanup: work items + plan links, per-asset plan rows (branch/PR fields), repo paths, provenance columns; default-org bootstrap, org-membership access model
• v0.2.1 — Work items & tech debt UI: backlog views, debt register by asset/area, activity feed (event log)
• v0.2.2 — Dependency mapping & impact analysis; analytics wired to real data
• v0.2.3 — Integrations framework + first connector (GitHub Issues), pull-only sync
• v0.2.4 — Task-level sync & mixed plans; PR auto-linking
• v0.2.5 — GitLab Issues connector (incl. self-hosted instances)
• v0.3.0 — Write-back: plan-completion comments on mirrored tracker issues; deprecated plan array columns dropped
• v0.3.1 — MCP server: API-key auth, 13 tools for Claude Code/Desktop
• v0.3.2 — MCP management tools: products, assets, dependencies, plan lifecycle/targets (25 tools total)
• v0.3.4 — Linked design specs: Spec URL on plans/work items, read-only in-app markdown rendering (private repos via connection tokens)
• v0.3.5–v0.3.9 — Agent-driven modeling & spec polish: modeling guidance in MCP tools + monorepo modeling guide, re-runnable modeling (reconcile + dedup), docs-corpus capture support, spec rendering in work-item panels, paginated list views
• v0.3.10–v0.3.16 — Editing & workflow UX: auto-save panels, inline row editing, quick-add & bulk select, invite emails, My Work view, task scheduling dates, plan-centric task editing; paste-able integration tokens encrypted at rest
• v0.3.17 — Jira / Asana / Linear connectors (pull-only mirror), edit-connection UI, "Me" filters
• v0.3.18–v0.3.23 — UI refinement: agent connect snippets beside API key generation, light/dark/system theme switcher, Code Plan detail redesign, plan assignees derived from task assignment, Work Items filters + reworked Tech Debt Register, persisted view preferences
• v0.3.24–v0.3.25 — Asset ownership & detail page: code owners (routing & visibility), asset detail page with notes/ideation doc
• v0.3.26–v0.3.29 — Rich text editing: TipTap editor (markdown + GFM canonical) and markdown rendering for plan descriptions; MCP connect snippets for Codex, Copilot & Antigravity
• v0.4.0 — Derived asset history: History tab on assets — plans delivered, work items resolved, debt movement, projected from existing data
• v0.4.1 — Releases: delivery grouping above code plans with per-asset version stamps, derived work-item rollups (release notes), ship lifecycle
• v0.4.2 — Version-structured history & design log: version ladder on asset history, user/agent-authored design notes, plan-side release picker, 10 new MCP tools (39 total)
• v0.4.3 — AI drafting (feature-flagged): release notes & design notes drafted from delivered work, always landing in an editor
• v0.4.4 — Asset Record (Phase A): per-asset capabilities register with delivery lineage, graduation from resolved work items, derived known-issues/debt sections, tombstoned removals, get_asset_record + graduate_work_item MCP tools (41 total)
• v0.4.5 — Asset Atlas (see docs/specs/asset-atlas-spec.md): top-level Assets view — a live system map (products as columns, dependency edges, health/debt/activity lenses, blast-radius hover) plus grid and sortable table views
• v0.4.6 — Layers & model boundaries (see docs/specs/layers-and-boundaries-spec.md): asset layer field with display-time type defaults, Atlas layer columns (auto for single-product scope), move_asset model refactoring, boundary rule + layer taxonomy in the MCP modeling guide (42 tools)
• v0.4.7 — Native Specs: first-class versioned specs, asset/plan/work-item associations, pinned delivery receipts, legacy URL import, and consistent GFM rendering
• v0.5.0 — Product Wiki: full-window asset pages and document readers, product-wide search, contextual links, versions, timestamps, and creator/editor attribution
• v0.5.1 — Deletion, cascade safety & audit trail: MCP delete tools for tasks, work items, plans & releases with blast-radius disclosure; confirmation dialogs on every destructive UI action; a centralized audit log covering every mutation across the UI and MCP; standardized creator/updater attribution with a data backfill for pre-existing rows; role-based delete authorization (org owner/admin vs. creator-or-assignee-only for everyone else); and a fixed privilege-escalation gap in team role management
• v0.5.2 — Asset archive & attribution visibility: Asset delete replaced with a reversible archive/soft-delete tombstone — hidden from lists/pickers/Atlas but nothing referencing it is touched — plus archive_asset/restore_asset MCP tools disclosing reference counts; createdById/updatedById now exposed through the query layer (plans, tasks, work items, releases), closing a gap from v0.5.1 where attribution was backfilled but never surfaced to readers
• v0.5.3 — Product archive & hardened authorization: Product hard-delete replaced with the same archive/soft-delete tombstone, the highest blast radius in the schema — nothing beneath a product (assets, plans, releases, work items, specs) is touched, it just stops resolving until restored; archive_product/restore_product MCP tools; typed-name confirmation with a full blast-radius breakdown in the UI; and a closed access-control gap where updateAssetAction had no check that the asset was actually accessible to the caller. Completes the deletion & audit initiative started in v0.5.1
• Collaboration loop (next release) (see docs/specs/collaboration-review-notifications-spec.md): responsibilities, plan and spec reviews pinned to a version with Open/Guided workflows, anchored comments with @mentions, spec revision history and diffs, the My Work inbox with role lenses and evidence gaps, and notifications in-app, by email (Resend) and to Slack with admin rules, opt-outs and mutes
• Planned — Reconciliation & round-trip engineering (see docs/specs/asset-record-spec.md): agent reconciliation proposals, release publishing
• AI-assisted effort estimation
• Billing / subscription management (hosted tier, optional & feature-flagged)

See docs/app-spec.md for the full current state of the app, and docs/specs/design-spec-v3.md for the target design and detailed roadmap.

MIT — see LICENSE.

Built by Sai Prakash · Sign up for the beta