cortexcode

Rust migration of the HooCode TypeScript coding-agent framework.

This is a multi-crate workspace that mirrors the structure of the pycortex Python migration. Each namespace (ai, agent, code, tui) is split into focused, version-locked crates published to crates.io.

crates/
  cortexcode/              # Top-level umbrella crate
  cortexcode-ai/           # AI namespace umbrella
  cortexcode-ai-types/
  cortexcode-ai-models/
  ...
  cortexcode-agent/        # Agent namespace umbrella
  cortexcode-agent-core/
  ...
  cortexcode-code/         # Code namespace umbrella
  ...
  cortexcode-tui/          # TUI namespace umbrella
  ...

All crates share a single lockstep version defined in the workspace Cargo.toml.

macOS / Linux (no root, no Node):

curl -fsSL https://kolisachint.github.io/hoocode/install.sh | sh

It installs ~/.hoocode/bin/hoocode (and hoo), checks the download against the release's SHA256SUMS, and adds ~/.hoocode/bin to PATH. --help lists the options (--version, --dir, --no-modify-path).

npm / bun:

npm install -g @kolisachint/hoocode     # or: bun add -g @kolisachint/hoocode

The package pulls in only the binary for your platform (macOS or Linux, x64 or arm64). There is no Windows build; on Windows use the TypeScript build, hoocode-ts.

This Rust build is installed as hoocode. The TypeScript original is reached as hoocode-ts, a small shim (scripts/shims/hoocode-ts) that runs the npm package @kolisachint/hoocode-agent (a global npm install if present, otherwise npx; set HOOCODE_TS_BIN to point it anywhere else). Only the installed names changed: the crates, the cargo binary (cortex), the config directory and the in-app name are unchanged. If you also have the TS one installed globally from npm, put the Rust hoocode earlier on PATH (npm's hoo alias still runs the TS one).

git clone https://github.com/kolisachint/cortexcode
cd cortexcode
scripts/install.sh                     # → updates ~/.hoocode/bin/hoocode if installed, else ~/.local/bin
scripts/install.sh --prefix /usr/local/bin --also-cortex   # also keep a `cortex` link

Plain cargo still works and installs the binary as cortex: cargo install --path crates/cortexcode-code-main --bin cortex.

Download hoocode-<target>.tar.gz from the GitHub Releases page and check it against SHA256SUMS. It holds the hoocode binary and the hoocode-ts shim; put both on your PATH. Linux builds are static (musl) and run on any distro.

# Single-shot print mode (text or JSON)
cortex -p "Explain this codebase"
cortex -p --mode json "Explain this codebase"

# Interactive TUI mode
cortex

# JSON-RPC server mode
cortex --mode rpc

# Subagent mode (used internally by the Task tool)
cortex --mode subagent --task-id <id>

# Build the entire workspace
cargo build

# Run checks for all crates
cargo check --workspace

# Run all tests (CI uses nextest; `cargo test --workspace` works too)
scripts/ci/fetch_hoocode_fixtures.sh   # pinned hoocode fixtures a few tests read
cargo nextest run --workspace

Label a PR rust:patch, rust:minor or rust:major; merging it runs the release: CI gates (parallel) → version bump, tag and GitHub release → binaries for 4 targets in parallel, each uploaded as soon as it is built. Optional labels: release:skip-gates (skip the gates, the PR's CI already passed) and release:crates (also publish to crates.io, off by default). Manual runs: Actions → Release.

The port of hoocode v0.6.0 (commit 2223437c) is paused, and cortex is usable as a daily coding agent. Phases 7, 8 and 11 are complete. Phase 10 is complete apart from the deferred items listed below. Every remaining task is deferred by user decision; none is in progress. Status per task: python3 migration/ledger.py status.

What works (the pinned hoocode behavior, checked against hoocode itself):

• Modes: interactive TUI, print mode (-p, text and --mode json), and --mode rpc (with a Rust RpcClient).
• Providers: every catalog provider, plus OAuth logins (/login) and models.json.
• Sessions: AgentSession with compaction, /new, /resume, /fork, /tree, --continue, --session, and /export <file>.jsonl.
• Tools: read, bash, edit, write, lexical SearchCodebase, TodoWrite, ask_options, and the Yes/No/Always permission prompt.
• Agent modes: ask/plan/build/debug (/mode, /plan, /grill, /approve, alt+a).
• Subagents: the Task/TaskOutput tools, the task panel, and the subagent roster.
• Resources: skills, prompt templates and slash commands, AGENTS.md/CLAUDE.md context files, themes, settings (/settings) and keybindings.

Deferred (not available yet, even though --help still lists some of them):

Known parity gaps: tasks 10.2a/b/c/d/f/g, 10.4c and 10.5 pass Level 1 but not Level 2. The default-bundle system prompt in hoocode also advertises the SearchHooCode self-knowledge tool from 12.4, so model requests differ in that one block.

The plan and its rationale are in docs/design/hoocode-to-cortexcode-migration.md (§0 status, §9 phases), and the handoff log is in migration/PROGRESS.md. To resume, take a deferred task out of deferred and say "continue migration" (see CLAUDE.md).

cargo install --path crates/cortexcode-code-main --bin cortex   # puts `cortex` on PATH
export ANTHROPIC_API_KEY=...        # or any provider key from `cortex --help`, or /login
cortex                              # interactive TUI
cortex -p "Summarize this repo"     # one-shot

• Config, auth, sessions and settings live in ~/.cortexcode/agent (override with CORTEX_CODING_AGENT_DIR). Project overrides go in ./.cortexcode/.
• The settings, models.json, auth.json, session JSONL and hoo-config.json formats match hoocode's, so an existing hoocode setup can be copied over.

Publishing is driven from GitHub Actions:

• Reserve crates.io names — one-off workflow that publishes 0.0.1 placeholder crates.
• Release — bump, build, publish, and create a GitHub release.
• Merge Release — auto-releases PRs labeled rust:patch, rust:minor, or rust:major.
• Build binaries — cross-compiles the cortex binary for Linux, macOS (Intel/Apple Silicon), and Windows.

Crates marked with [package.metadata.cortex] publish = true are included in automated releases.