Contribute to ctxindex

ctxindex is pre-alpha and developed in public. Start from a GitHub issue and read CONTRIBUTING.md before changing behavior.

Set up the workspace

ctxindex pins Bun 1.3.14 and uses Bun workspaces with Turborepo.

bun install
bun cli --help
bun dev

Use package-owned focused commands while iterating:

bun test <focused-test-file>
bun run --cwd apps/web typecheck
bun run --cwd apps/web build

Before completing a non-trivial change, run the repository gates:

bun run ci
bun run test:integration
bun run test:e2e
bunx openspec validate --all --strict

The test lanes are separate so pull requests can run them in parallel. Worktrees created by the repository helper also isolate CLI state, preventing one change from reusing another worktree's database, config, or installed Extensions.

Find the source of truth

The public CLI composes private core, Adapter, Profile, and Extension SDK workspaces. Extensions import the public SDK facade and ordinary definition packages; they do not import runtime internals. The website projects those contracts without owning product behavior or user state.

The CLI is the only agent integration surface. Do not add an MCP server, an agent-specific integration layer, arbitrary Extension command families, or provider mutations beyond reversible email Drafts.

Prove the change

1. Add a failing reproduction for a bug or a focused test for new behavior.
2. Pass each focused task and Slice gate before moving on.
3. Refresh affected codemap.md files after structural changes.
4. Never commit secrets or .env files, delete user data under ~/.local/share/ctxindex without consent, or use live provider traffic when fixtures prove the contract.

Use the live /design specimen and public /brand assets for visual work instead of inventing parallel tokens or logo geometry.