Contributing

Development Setup¶

Prerequisites¶

• Go (version defined in go.mod)
• Claude Code
• Git
• GNU Make
• Zensical

1. Fork (or Clone) the Repository¶

# Fork on GitHub, then:
git clone https://github.com/<you>/ctx.git
cd ctx

# Or, if you have push access:
git clone https://github.com/ActiveMemory/ctx.git
cd ctx

2. Build and Install the Binary¶

make build
sudo make install

This compiles the ctx binary and places it in /usr/local/bin/.

3. Install the Plugin from Your Local Clone¶

The repository ships a Claude Code plugin under internal/assets/claude/. Point Claude Code at your local copy so that skills and hooks reflect your working tree: no reinstall needed after edits:

1. Launch claude;
2. Type /plugin and press Enter;
3. Select Marketplaces → Add Marketplace
4. Enter the absolute path to the root of your clone, e.g. ~/WORKSPACE/ctx (this is where .claude-plugin/marketplace.json lives: it points Claude Code to the actual plugin in internal/assets/claude);
5. Back in /plugin, select Install and choose ctx.

make plugin-reload   # then restart Claude Code

4. Verify¶

ctx --version       # binary is in PATH
claude /plugin list # plugin is installed

You should see the ctx plugin listed, sourced from your local path.

Project Layout¶

ctx/
├── cmd/ctx/            # CLI entry point
├── internal/
│   ├── assets/claude/  # ← Claude Code plugin (skills, hooks)
│   ├── bootstrap/      # Project initialization templates
│   ├── claude/         # Claude Code integration helpers
│   ├── cli/            # Command implementations
│   ├── config/         # Configuration loading
│   ├── context/        # Core context logic
│   ├── crypto/         # Scratchpad encryption
│   ├── drift/          # Drift detection
│   ├── index/          # Context file indexing
│   ├── journal/        # Journal site generation
│   ├── memory/         # Memory bridge (discover, mirror, import, publish)
│   ├── notify/         # Webhook notifications
│   ├── rc/             # .ctxrc parsing
│   ├── recall/         # Session history and parsers
│   ├── sysinfo/        # System resource monitoring
│   ├── task/           # Task management
│   └── validation/     # Input validation
├── .claude/
│   └── skills/         # Dev-only skills (not distributed)
├── assets/             # Static assets (banners, logos)
├── docs/               # Documentation site source
├── editors/            # Editor extensions (VS Code)
├── examples/           # Example configurations
├── hack/               # Build scripts and runbooks
├── specs/              # Feature specifications
└── .context/           # ctx's own context (dogfooding)

Skills: Two Directories, One Rule¶

internal/assets/claude/skills/ is the single source of truth for user-facing skills. If you are adding or modifying a ctx-* skill, edit it there.

.claude/skills/ holds skills that only make sense inside this repository (release automation, QA checks, backup scripts). These are never distributed to users.

Dev-Only Skills Reference¶

Six skills previously in this list have been promoted to bundled plugin skills and are now available to all ctx users: /ctx-brainstorm, /ctx-check-links, /ctx-sanitize-permissions, /ctx-skill-creator, /ctx-spec, /ctx-verify.

How To Add Things¶

Adding a New CLI Command¶

1. Create a package under internal/cli/<name>/;
2. Implement Cmd() *cobra.Command as the entry point;
3. Register it in internal/bootstrap/bootstrap.go (add import + call in Initialize);
4. Use cmd.Printf/cmd.Println for output (not fmt.Print);
5. Add tests in the same package (<name>_test.go);
6. Add a section to the appropriate CLI doc page in docs/cli/.

Pattern to follow: internal/cli/pad/pad.go (parent with subcommands) or internal/cli/complete/complete.go (single command).

Adding a New Session Parser¶

The recall system uses a SessionParser interface. To add support for a new AI tool (e.g. Aider, Cursor):

1. Create internal/recall/parser/<tool>.go;
2. Implement parsing logic that returns []*Session;
3. Register the parser in FindSessions() / FindSessionsForCWD();
4. Use config.Tool* constants for the tool identifier;
5. Add test fixtures and parser tests.

Pattern to follow: the Claude Code JSONL parser in internal/recall/parser/.

Adding a Bundled Skill¶

1. Create internal/assets/claude/skills/<skill-name>/SKILL.md;
2. Follow the skill format: trigger, negative triggers, steps, quality gate;
3. Run make plugin-reload and restart Claude Code to test;
4. Add a Skill entry to .claude-plugin/plugin.json if user-invocable;
5. Document in docs/reference/skills.md.

Pattern to follow: any skill in internal/assets/claude/skills/ctx-status/.

Test Expectations¶

• Unit tests: colocated with source (foo.go → foo_test.go);
• Test helpers: use t.Helper() so failures point to callers;
• HOME isolation: use t.TempDir() + t.Setenv("HOME", ...) for tests that touch ~/.claude/ or ~/.ctx/;
• rc.Reset(): call after os.Chdir in tests that change working directory (rc caches on first access);
• No network: all tests run offline, use fixtures.

Run make test before submitting. Target: no failures, no skips.

Day-to-Day Workflow¶

Go Code Changes¶

After modifying Go source files, rebuild and reinstall:

make build && sudo make install

The ctx binary is statically compiled. There is no hot reload. You must rebuild for Go changes to take effect.

Skill or Hook Changes¶

Edit files under internal/assets/claude/skills/ or internal/assets/claude/hooks/.

Claude Code caches plugin files, so edits aren't picked up automatically.

Clear the cache and restart:

make plugin-reload   # nukes ~/.claude/plugins/cache/activememory-ctx/
# then restart Claude Code

The plugin will be re-installed from your local marketplace on startup. No version bump is needed during development.

Configuration Profiles¶

The repo ships two .ctxrc source profiles. The working copy (.ctxrc) is gitignored and swapped between them:

Use ctx commands to switch:

ctx config switch dev      # switch to dev profile
ctx config switch base     # switch to base profile
ctx config status          # show which profile is active

After cloning, run ctx config switch dev to get started with full logging.

See Configuration for the full .ctxrc option reference.

Backups¶

Back up project context and global Claude Code data with:

ctx system backup                    # both project + global (default)
ctx system backup --scope project    # .context/, .claude/, ideas/ only
ctx system backup --scope global     # ~/.claude/ only

Archives are saved to /tmp/. When CTX_BACKUP_SMB_URL is configured, they are also copied to an SMB share. See CLI Reference: backup for details.

Running Tests¶

make test   # fast: all tests
make audit  # full: fmt + vet + lint + drift + docs + test
make smoke  # build + run basic commands end-to-end

Running the Docs Site Locally¶

make site-setup  # one-time: install zensical via pipx
make site-serve  # serve at localhost

Submitting Changes¶

Before You Start¶

1. Check existing issues to avoid duplicating effort;
2. For large changes, open an issue first to discuss the approach;
3. Read the specs in specs/ for design context.

Pull Request Process¶

Respect the maintainers' time and energy: Keep your pull requests isolated and strive to minimze code changes.

If you Pull Request solves more than one distinct issues, it's better to create separate pull requests instead of sending them in one large bundle.

1. Create a feature branch: git checkout -b feature/my-feature;
2. Make your changes;
3. Run make audit to catch issues early;
4. Commit with a clear message;
5. Push and open a pull request.

Commit Messages¶

Following conventional commits is recommended but not required:

Types: feat, fix, docs, test, refactor, chore

Examples:

• feat(cli): add ctx export command
• fix(drift): handle missing files gracefully
• docs: update installation instructions

Code Style¶

• Follow Go conventions (gofmt, go vet);
• Keep functions focused and small;
• Add tests for new functionality;
• Handle errors explicitly.

Code of Conduct¶

A clear context requires respectful collaboration.

ctx follows the Contributor Covenant.

Boring Legal Stuff¶

Developer Certificate of Origin (DCO)¶

By contributing, you agree to the Developer Certificate of Origin.

All commits must be signed off:

git commit -s -m "feat: add new feature"

License¶

Contributions are licensed under the Apache 2.0 License.