contextcart

README

ContextCart

ContextCart is a local-first Go CLI/TUI for keeping AI coding-agent capabilities lean, inspectable, and reversible. It stores reusable MCP servers, skills, rules, ignore templates, and loadouts in a local ContextCart store, then plans and applies only the project-scoped agent configuration a project needs.

The v1 implementation targets Claude Code, Codex CLI, and OpenCode. It is not an agent runtime, cloud service, hosted marketplace, desktop GUI, daemon, or global agent config mutator.

Install

ContextCart release builds are single native binaries. End users do not need Go, Git, Node, Python, Homebrew, Scoop, or Winget.

You can run the installer from any folder; it installs the contextcart binary into a user-accessible bin directory, not into the current working directory.

macOS and Linux:

curl -fsSL https://raw.githubusercontent.com/sumowhiz/contextcart/master/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/sumowhiz/contextcart/master/scripts/install.ps1 | iex

To install a specific release and avoid the GitHub latest-release API lookup:

curl -fsSL https://raw.githubusercontent.com/sumowhiz/contextcart/master/scripts/install.sh | sh -s -- --version v1.0.0

$env:CONTEXTCART_VERSION = "v1.0.0"; irm https://raw.githubusercontent.com/sumowhiz/contextcart/master/scripts/install.ps1 | iex

Default install locations:

• macOS: /usr/local/bin/contextcart when writable, otherwise $HOME/.local/bin/contextcart.
• Linux: $HOME/.local/bin/contextcart.
• Windows: %LOCALAPPDATA%\ContextCart\bin\contextcart.exe.

Set CONTEXTCART_INSTALL_DIR to choose a different install directory.

Inspect before running:

curl -fsSL https://raw.githubusercontent.com/sumowhiz/contextcart/master/scripts/install.sh -o install.sh
less install.sh
sh install.sh

iwr https://raw.githubusercontent.com/sumowhiz/contextcart/master/scripts/install.ps1 -OutFile install.ps1
notepad install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

Build From Source

ContextCart is a single Go binary. It requires Go 1.24.2 or newer for local source builds.

git clone https://github.com/sumowhiz/contextcart.git
cd contextcart
go build -o dist/contextcart .

For local development, you can also run commands directly:

go run . --help

To install from a checked-out source tree into your Go binary path:

go install .

Uninstall

Remove the installed binary:

rm -f /usr/local/bin/contextcart
rm -f "$HOME/.local/bin/contextcart"

Windows PowerShell:

Remove-Item "$env:LOCALAPPDATA\ContextCart\bin\contextcart.exe" -ErrorAction SilentlyContinue

If you used CONTEXTCART_INSTALL_DIR, remove contextcart or contextcart.exe from that directory instead.

To remove the local ContextCart store, delete $HOME/.contextcart or the directory pointed to by CONTEXTCART_HOME.

Project metadata, backups, and lockfiles live under each modified project's .contextcart/ directory. If you attached capabilities to a project, run contextcart detach ... or contextcart rollback ... before deleting the binary when you want ContextCart to clean up project files itself.

If you manually added the install directory to PATH, remove that shell profile or Windows user PATH entry separately.

Core Commands

• contextcart launches the interactive TUI when run in an interactive terminal, and prints help when run non-interactively.
• contextcart store init creates the local store under ~/.contextcart or CONTEXTCART_HOME.
• contextcart store path prints the resolved store path.
• contextcart store doctor validates the store layout and readable metadata.
• contextcart mcp|skill|rule|ignore add|list|show|remove manages normalized component records.
• contextcart loadout list|show|validate|create|add|remove-component|delete manages named kits such as Web App Builder Kit, WordPress Builder Kit, and Browser QA Kit.
• contextcart adapter list|show|create|validate inspects built-in adapter support and manages safe custom adapter manifests.
• contextcart audit <project> scans active agent capabilities without writing files.
• contextcart suggest --project <path> recommends loadouts from static project signals.
• contextcart plan kit <id> <project> --agents <ids> previews attachment operations without writing files.
• contextcart diff kit <id> <project> --agents <ids> renders native config diffs for the same read-only plan.
• contextcart attach kit <id> <project> --agents <ids> applies a confirmed plan, creates backups, and records ownership in .contextcart/lock.yaml.
• contextcart detach kit <id> <project> --agents <ids> removes only recorded ContextCart-owned attachments.
• contextcart clean <project> reports stale lock entries, missing targets, and orphaned backups without deleting user files.
• contextcart rollback <project> previews and restores the latest or selected recorded operation from backups.
• contextcart import <path> --format <codex|opencode|claude|mcp-json|rule|skill> imports supported existing config into the local store without attaching it.
• contextcart version prints the binary version.

Most planning and mutation commands support --json, --agents, --scope, --yes, --dry-run, and --contextcart-home where applicable. Interactive prompts are disabled when stdout is not a terminal unless a command has an explicit non-interactive path such as --yes or --dry-run.

Feature Surface

• Local store for MCP servers, skills, rules, ignore templates, loadouts, custom adapters, project lockfiles, and backups.
• Loadout-first workflow with seeded Web App Builder, WordPress Builder, and Browser QA kits.
• Project-scoped attach, detach, clean, and rollback for Claude Code, Codex CLI, and OpenCode.
• Read-only audit and suggestion flows for existing project capability surface.
• Import preview for existing Codex, OpenCode, verified Claude MCP, generic MCP JSON, Markdown rules, and supported skill directories.
• Full skill-directory install for built-in adapters, including SKILL.md, references/, and examples/, with unowned target directory collision protection.
• Detach rollback snapshots so the latest detach can be rolled back without silently selecting an older attach operation.
• Secret and risk warnings with redacted output and explicit raw-secret opt-in.

Safety Model

ContextCart is project-scoped in v1. Attach and detach write only inside the selected project, and never install global/user agent configuration.

Every write goes through a deterministic plan and diff preview before confirmation unless --yes is passed. The writer creates backups for changed files, records ownership in <project>/.contextcart/lock.yaml, and detaches only entries that ContextCart created.

Raw-looking secrets are redacted in audit and import output. ContextCart stores environment variable references by default and rejects raw-looking secret writes unless --allow-raw-secret is explicitly provided.

When symlink installation is unavailable or denied, skill attachment falls back to copy mode and records the actual install mode in the project lockfile. Built-in skill attach writes the containing skill directory, not only SKILL.md, and detach removes copied skill directories only when ownership and content checks pass.

Starter Examples

Use a temporary store while trying ContextCart:

export CONTEXTCART_HOME="$(mktemp -d)"
contextcart store init
contextcart loadout list

Audit the current project without writing files:

contextcart audit . --json

Preview a kit for Codex CLI before applying it:

contextcart plan kit wordpress-builder . --agents codex
contextcart diff kit wordpress-builder . --agents codex

Apply the same kit only after reviewing the plan:

contextcart attach kit wordpress-builder . --agents codex --yes

Remove only ContextCart-owned attachments later:

contextcart detach kit wordpress-builder . --agents codex --yes
contextcart clean . --json

Import an existing Codex MCP config into the local store without attaching it:

contextcart import .codex/config.toml --format codex --yes

Import a Markdown rule into the local store without attaching it:

contextcart import docs/team-rule.md --format rule --yes

Operational Docs

• Local macOS validation: docs/local_testing.md
• Release and deployment packaging: docs/deployment.md
• Cross-platform smoke matrix: docs/smoke-tests.md
• TUI smoke checks: docs/tui-smoke.md
• Adapter support matrix: docs/adapter-inventory.md
• Distribution and product roadmap: ROADMAP.md

License And Security

ContextCart CLI/TUI v1 is MIT licensed. Report security issues through GitHub's private vulnerability reporting for sumowhiz/contextcart; do not open public issues for suspected vulnerabilities.

V1 Exclusions

ContextCart v1 does not provide cloud sync, hosted sharing, a GUI desktop app, background daemon behavior, runtime agent orchestration, arbitrary hook execution, encrypted secret storage, global attach/detach, or built-in adapters outside Claude Code, Codex CLI, and OpenCode.

Unsupported agents can be explored through custom adapter manifests, but v1.0 custom adapters are limited to create, validate, list, and detect flows. Template-backed custom adapter attach/write rendering is deferred to v1.1 for a dedicated security review. ContextCart v1 does not claim built-in support for Kiro, Amp, Goose, Pi, Droid, Kilo, Warp, or Antigravity until their adapter inventory is specified and tested.

Release Builds

Release packaging is configured through .goreleaser.yaml for macOS, Linux, and Windows archives with checksums. The install scripts download and verify those GitHub Release artifacts. The first release config does not publish Homebrew, Scoop, or Winget manifests. See docs/deployment.md for exact release commands.