Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
Contributing to Ix
Getting Started
Prerequisites
- Node.js 22+ (22.22 or newer to build the docs site, which Astro requires)
- Docker and Docker Compose
Local Setup
git clone https://github.com/ix-infrastructure/Ix.git
cd Ix
./scripts/backend.sh up # Start ArangoDB + Memory Layer (Docker)
cd ix-cli && npm ci && npm run build
Building from Source
# core-ingestion (parser library, built automatically by ix-cli)
cd core-ingestion
npm ci
npm run build
# ix-cli
cd ../ix-cli
npm ci
npm run build
Verify Your Setup
# CLI tests
cd ix-cli && npm test
Development Workflow
- Create a branch from
main - Make your changes
- Run tests locally
- Open a PR using the pull request template
- Ensure CI passes before merge
Branch Naming
feat/<name>
fix/<name>
docs/<name>
refactor/<name>
test/<name>
ci/<name>
chore/<name>
Commit Format
Use conventional commit prefixes:
feat: New feature
fix: Bug fix
docs: Documentation only
refactor: Code change that neither fixes a bug nor adds a feature
test: Adding or updating tests
ci: CI/CD changes
chore: Maintenance, dependencies, tooling
Breaking changes: use feat!: or fix!: prefix.
Testing
| What changed | Run |
|---|---|
| CLI code | cd ix-cli && npm test |
| Any change | Full test suite before opening PR |
CLI Standards
Output quality
- Clean, minimal output — no unnecessary verbosity
- Consistent formatting across all commands
Error handling
- No raw stack traces in normal mode
- Use the structured error system (
ix-cli/src/cli/errors.ts) --debugmay show detailed output
Language consistency
- Follow existing Ix command voice and terminology
- Match output patterns of existing commands
Exit codes
The graph commands share one set of codes, defined in
ix-cli/src/cli/outcome.ts: 0 results, 1 error, 2 ambiguous target,
3 target not found, 4 workspace not mapped (IX_LEGACY_EXIT_CODES=1
collapses 2-4 to 1). A hook that runs ix exits with its own status, never
ix's: Claude Code treats a hook's exit 2 as a block. Report a resolution
failure through resolveFileOrReport or reportResolutionFailure rather than
setting process.exitCode yourself,
and the right code follows. ix read's ambiguity is the one exception: it
exits 0 with its own ambiguous record, as it always has (see below for why
adding a non-zero exit is not free).
Making a command exit non-zero is a breaking change to every plugin and MCP client, even when the payload it prints is an improvement. Both consumers throw stdout away on a failed run:
- Plugins run
ixthrough wrappers that treat a non-zero exit as an error and discard the output — bun's$`…`throws, and the shell hooks branch on||underset -euo pipefail. ix mcpprefers stderr over stdout when the exit is non-zero (runCommandinix-cli/src/mcp/server.ts), so a structured record written to stdout is replaced by whatever prose happened to reach stderr — usually the resolver's human guidance.
The failure mode is counter-intuitive: you add {"error": "...", "message": "..."}
so machine callers can tell a refusal from an empty result, set the exit code
to match, and the exit code is what stops anyone from ever seeing the payload.
Before adding a non-zero exit to an existing command, check whether anything calls it programmatically:
# from a directory holding checkouts of the plugin repos
grep -rnE '\$`ix <command>|runIx\(\["<command>"|\$\(ix <command>' . | grep -v '\.md:'
Those three forms cover every call site today — bun shell, the TypeScript
runIx helper, and shell command substitution. They are literal on purpose:
no plugin builds the command name from a variable, so a literal search is
exhaustive. Re-check that assumption if the grep comes back empty for a command
you expected to find.
Matches in .md files or agent prompt strings are prose telling a model to run
the command — those are fine, the model sees stdout either way. Matches in
.ts, .sh or .py are runners, and those break.
If a runner consumes it, the plugin change has to land first, in its own repo, and the Ix change follows. Say so in the PR body and open it as a draft until the dependency is merged.
Applies to: ix-claude-plugin, ix-codex-plugin, ix-cursor-plugin,
ix-gemini-plugin, ix-openclaw-plugin, ix-opencode-plugin. Five of the six
carry runners today, so "no plugin calls this" is a claim to verify, not
assume.
Copyright Headers
Every source file starts with the copyright line, in that language's comment syntax:
// Copyright 2026 Ix Infrastructure Inc.
A shebang stays on line 1 — the header goes directly beneath it. This is enforced
by the Lint & Typecheck job, so it gates merges through the required CI Passed
check. If you add a file and it goes red, fix every offender at once:
python3 .github/scripts/copyright-headers.py --fix
Test fixtures, vendored code, and anything marked linguist-generated in
.gitattributes are deliberately exempt — the parser tests snapshot fixture line
numbers, and generated files lose the header on their next regeneration.
Security Checks
PRs and pushes to main run automated security checks:
- Dependency review — flags new dependencies with known vulnerabilities (PRs only)
- Trivy scanning — scans the repo filesystem and Docker image for vulnerabilities and misconfigurations
- Config security — scans Docker Compose and deployment configs for unsafe exposure (e.g., auth disabled with public port bindings,
0.0.0.0bindings). Local-only configs that bind to127.0.0.1are allowed.
All checks fail on CRITICAL or HIGH severity findings. If a check fails on your PR, inspect the output and either fix the vulnerability or document why it's a false positive.
Backend Development
The Scala memory-layer backend is developed in a separate, private repository
(ix-infrastructure/Ix-memory). Its source is not publicly accessible, so cloning
it is a maintainer-only step. Note that ix-memory-layer — the name used in the
release notes, docker-compose.standalone.yml and the image path in
.github/workflows/ — is the published artifact, not a repository you can
clone.
You do not need the backend source to work on this repository. Everything in
the ix CLI is developed against the published backend image, which is public and
pullable anonymously. ./scripts/backend.sh up in Local Setup
starts it (ghcr.io/ix-infrastructure/ix-memory-layer:latest on
127.0.0.1:8090, plus ArangoDB with no host port). It installs nothing itself — it runs
docker compose -f docker-compose.standalone.yml against an already-installed
Docker. What the curl | sh installer puts on the machine is a separate list:
docs/prerequisites.md.
If a change you want needs the backend itself — a new endpoint, a different
response shape, a query that is too slow — open an issue here describing the CLI
behaviour you need and what the backend would have to do. A maintainer will carry
it across. Please do not open a PR against this repository that assumes an
endpoint the released backend does not serve. ix doctor reports the running
graph schema version, and curl -s localhost:8090/v1/health returns both that
and the backend's release version — that release is what to write against.
OSS vs Pro Boundary
This repository contains open-source Ix functionality. Some features are available only in Ix Pro.
Contributors must:
- Not reintroduce Pro-only features into this repository
- Not bypass licensing boundaries
- Respect the separation between OSS and Pro functionality
If you're unsure whether a feature belongs in OSS or Pro, ask in your PR.