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.

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

Why CodePlans?

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

Features

Feature	Status
Products & asset inventory	✅ Available
Product, asset, plan & task create/edit (side panels & quick modals)	✅ Available
Workspace product switcher (filter all pages by product)	✅ Available
Tech debt scoring per asset	✅ Available
Code Plans with status lifecycle (draft → active → completed)	✅ Available
Task management (list & kanban views, deep-linkable task panel)	✅ Available
Dashboard with velocity metrics	✅ Available
Organization & team management	✅ Available
Role-based access (owner / admin / editor / viewer)	✅ Available
SQLite local mode (no cloud required)	✅ Available
Supabase + Postgres cloud mode	✅ Available
Pluggable auth (local password or Supabase)	✅ Available
Work items — features, bugs & tech debt register, linkable to code plans	✅ Available
Per-asset branch & PR tracking on code plans	✅ Available
Asset dependency mapping & plan impact analysis	✅ Available
Asset Atlas — live system map with health/debt/activity lenses, plus grid & table views	✅ Available
Analytics wired to real data (velocity, effort accuracy, debt by product)	✅ Available
Activity feed	✅ Available
GitHub, GitLab, Jira, Asana & Linear integrations (pull-only mirror into work items)	✅ Available
MCP server — 42 tools incl. product/asset/dependency management, model refactoring (move_asset), releases, asset design notes & the asset record	✅ Available
Milestone-linked plans with mirrored tasks (mixed mode)	✅ Available
PR auto-linking (plan-asset PR status refreshed on sync)	✅ Available
Releases — delivery grouping with per-asset version stamps & derived release notes	✅ Available
Asset history timeline, version ladder & design log (user + agent authored)	✅ Available
AI drafting — release notes & design notes (feature-flagged, `ANTHROPIC_API_KEY`)	✅ Available
AI-assisted effort estimation	🔜 Planned
Billing / subscription management	🔜 Planned (optional, feature-flagged)

Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router, Server Components)
Language	TypeScript 5.7
Styling	Tailwind CSS v4 + Radix UI primitives
ORM	Drizzle ORM
Database	SQLite (local / libsql) or PostgreSQL (cloud)
Auth	Local (bcrypt + session cookie) or Supabase
Charts	Recharts
Testing	Vitest (161 tests)

Deployment Modes

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

`HOST_MODE` — the deployment model

Value	Description
`team`	Single private team. One organisation, no open registration, billing UI hidden. The right default for self-hosted installs.
`saas`	Multi-tenant hosted. Multiple independent orgs can exist, open registration is possible, billing UI available.

`REGISTRATION` — who can create accounts

Value	Description
`closed`	`/signup` returns 404. Users are created by an admin via `pnpm db:seed` or a future admin CLI.
`invite`	`/signup` shows an invite-only message. (Token-based invite flow is planned.)
`open`	Anyone who can reach the server can sign up.

Common combinations

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

Getting Started

Prerequisites

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

Self-hosted team (SQLite, no cloud required)

# 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:

Field	Value
Email	`admin@example.com`
Password	`Password1!`

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.

Cloud (Supabase + Postgres) mode

# 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.

Environment variables

Variable	Default	Description
`PORT`	`3000`	Port the dev server binds to
`HOST_MODE`	`saas`	`team` (private self-hosted) or `saas` (multi-tenant hosted)
`REGISTRATION`	`open`	`closed`, `invite`, or `open` — controls who can create accounts
`AUTH_PROVIDER`	`local`	`local` (bcrypt + session cookie) or `supabase`
`DB_PROVIDER`	`sqlite`	`sqlite` or `postgres`
`DATABASE_URL`	`:memory:`	SQLite: `file:data/codeplans.db` or `:memory:`. Postgres: full connection string
`DB_SSL`	`true`	Set `false` for local or non-SSL Postgres
`AUTH_SECRET`	—	Secret for local auth session signing (min 32 chars)
(integration tokens)	—	Paste tokens directly on connections (stored AES-256-GCM-encrypted with a key derived from `AUTH_SECRET`), or reference a server env var by name for secrets-in-deployment postures
`AUTH_URL`	—	Required in production. Full URL of the server (e.g. `https://codeplans.yourteam.com`). Auth.js uses this to construct callback URLs and validate login redirects. Not needed for `localhost` dev.
`BILLING_ENABLED`	`true`	Set `false` to hide billing UI (always off in `team` mode)
`ALLOWED_DEV_ORIGINS`	—	Comma-separated hosts allowed to access Next.js dev resources (needed when running on a remote server)
`RESEND_API_KEY`	—	Resend API key for transactional email (email change verification, future invites). Without this, verification URLs are logged to the server console (dev only).
`RESEND_FROM_EMAIL`	`CodePlans <noreply@codeplans.ai>`	From address used in outgoing emails
`NEXT_PUBLIC_SUPABASE_URL`	—	Required for Supabase auth mode
`NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY`	—	Required for Supabase auth mode
`SUPABASE_SECRET_KEY`	—	Required for Supabase auth mode (server-side)

Project Structure

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

Database Schema

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}/.

Running Tests

pnpm test              # run all tests (88 tests across 3 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.

Database Scripts

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

Demo accounts

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

Name	Email	Role	Password
Alex Chen	`alex.chen@codeplans.local`	Owner	`Password1!`
Sarah Kim	`sarah.kim@codeplans.local`	Admin	`Password1!`
Mike Jones	`mike.jones@codeplans.local`	Editor	`Password1!`
Lisa Wang	`lisa.wang@codeplans.local`	Editor	`Password1!`
James Lee	`james.lee@codeplans.local`	Viewer	`Password1!`

The demo workspace includes 3 products, 15 assets, 9 code plans, and ~65 tasks across various stages.

Contributing

Contributions are welcome. To get started:

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

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

Design Specs

Specs live in git (docs/specs/*.md by convention), not in CodePlans. Link a spec's blob URL to any plan or work item via the Spec URL field: plan pages render the markdown read-only (private repos render through your GitHub/GitLab connection tokens; anything else is a link-out). See the specs guide, and the monorepo modeling guide for breaking large codebases into assets (Claude can do it for you via MCP).

Connect an AI coding agent (MCP)

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 plans/work items/tech debt and (with a write-scope key) 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.

Roadmap

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.

License

MIT — see LICENSE.

Built by Sai Prakash · Sign up for the beta

Name		Name	Last commit message	Last commit date
Latest commit History 144 Commits
.github/workflows		.github/workflows
app		app
components		components
data		data
docs		docs
hooks		hooks
lib		lib
public		public
styles		styles
supabase/sql		supabase/sql
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
components.json		components.json
drizzle.config.ts		drizzle.config.ts
instrumentation.ts		instrumentation.ts
next-env.d.ts		next-env.d.ts
next.config.mjs		next.config.mjs
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
postcss.config.mjs		postcss.config.mjs
proxy.ts		proxy.ts
tsconfig.json		tsconfig.json
tsconfig.tsbuildinfo		tsconfig.tsbuildinfo
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

CodePlans

Why CodePlans?

Features

Tech Stack

Deployment Modes

`HOST_MODE` — the deployment model

`REGISTRATION` — who can create accounts

Common combinations

Getting Started

Prerequisites

Self-hosted team (SQLite, no cloud required)

Cloud (Supabase + Postgres) mode

Environment variables

Project Structure

Database Schema

Running Tests

Database Scripts

Demo accounts

Contributing

Design Specs

Connect an AI coding agent (MCP)

Roadmap

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

CodePlans

Why CodePlans?

Features

Tech Stack

Deployment Modes

HOST_MODE — the deployment model

REGISTRATION — who can create accounts

Common combinations

Getting Started

Prerequisites

Self-hosted team (SQLite, no cloud required)

Cloud (Supabase + Postgres) mode

Environment variables

Project Structure

Database Schema

Running Tests

Database Scripts

Demo accounts

Contributing

Design Specs

Connect an AI coding agent (MCP)

Roadmap

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`HOST_MODE` — the deployment model

`REGISTRATION` — who can create accounts