A context engineering system for Claude Code

HOANGSA is a context engineering system for Claude Code that solves a fundamental problem: Claude's output quality degrades as the context window fills up. The fix is structural — HOANGSA splits work into discrete tasks, each running in a fresh context window with only the files it actually needs. The orchestrator never writes code; it dispatches workers with bounded context and assembles results.

HOANGSA ships four binaries: three CLIs you invoke directly (hoangsa-cli, hoangsa-memory, hsp) plus one MCP server (hoangsa-memory-mcp) that Claude Code spawns on your behalf.

Prerequisites on the target machine: curl or wget, tar, and one of sha256sum / shasum. No Node, no Python, no Docker, no cargo needed for the release tarball.

For contributors building from source you additionally need Rust 1.91+ (rustup toolchain install stable) and a C toolchain (build-essential on Debian/Ubuntu, Xcode Command Line Tools on macOS).

One command pulls the latest release, verifies the SHA-256 checksum, drops all four binaries into ~/.hoangsa/bin/, registers the hoangsa-memory MCP server in Claude Code, and pre-downloads the fastembed ONNX weights.

curl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh

Flags (pass after sh -s --):

Examples:

# Global install (default)
curl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh

# Project-local install
curl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh -s -- --local

# Dry-run to see what would happen
curl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh -s -- --dry-run

# Pin a specific version
HOANGSA_VERSION=v0.2.2 curl -fsSL https://github.com/pirumu/hoangsa/releases/download/v0.2.2/install.sh | sh

Environment overrides:

The installer honours CLAUDE_CONFIG_DIR if it is already set, and otherwise detects multiple Claude profile dirs (~/.claude, ~/.zclaude, …). With more than one it prompts; pass the env var explicitly in non-TTY installs.

Clone the repo and run the local install helper — builds the workspace in release mode, installs the four binaries, and wires Claude Code the same way the release installer does:

git clone https://github.com/pirumu/hoangsa.git
cd hoangsa
scripts/install-local.sh --global     # or --local for per-project

Flags: --global / --local, --dry-run, --no-embed, --skip-build (re-run the post-build steps without recompiling).

Just one CLI? Each binary can be installed standalone via cargo:

cargo install --path crates/hoangsa-cli       # installs `hoangsa-cli`
cargo install --path crates/hoangsa-memory    # installs `hoangsa-memory`
cargo install --path crates/hoangsa-memory-mcp # installs `hoangsa-memory-mcp`
cargo install --path crates/hoangsa-proxy     # installs `hsp`

This drops binaries into ~/.cargo/bin/. Note that cargo install alone does not register MCP servers, copy templates, or wire Claude Code hooks — run hoangsa-cli install --global afterwards to finish setup.

The installer appends a managed block to the first existing rc file it finds (~/.zshrc → ~/.bashrc) containing:

# hoangsa:managed start
export PATH="$HOME/.hoangsa/bin:$PATH"
# hoangsa:managed end

If the block was skipped (non-TTY install, declined prompt, HOANGSA_NO_PATH_EDIT=1, no rc file found), add it yourself:

echo 'export PATH="$HOME/.hoangsa/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify the install:

hoangsa-cli --version          # e.g. hoangsa-cli 0.2.2
hoangsa-memory --version       # e.g. hoangsa-memory 0.2.2
hoangsa-memory-mcp --version   # e.g. hoangsa-memory-mcp 0.2.2
hsp --version                  # e.g. hsp 0.2.2

Then run the per-CLI self-checks:

hsp doctor                     # verifies hsp hooks + handlers
hoangsa-memory memory show     # prints MEMORY.md + LESSONS.md for cwd

Drives the /hoangsa:* slash commands, owns the rule engine, wires Claude Code hooks, manages project preferences.

• Binary location: ~/.hoangsa/bin/hoangsa-cli
• Per-project config: .hoangsa/config.json (created by hoangsa-cli install --local or /hoangsa:init)
• Templates: staged to ~/.hoangsa/templates/ on global install
• First-run setup: /hoangsa:init from inside Claude Code, or hoangsa-cli install --local from the shell

No separate install step — bundled with the release installer.

Indexes your source tree, serves recall queries, runs blast-radius analysis, and manages the verbatim conversation archive.

• Binary: ~/.hoangsa/bin/hoangsa-memory
• Companion daemon: ~/.hoangsa/bin/hoangsa-memory-mcp (spawned by Claude Code via MCP — you never start it manually)
• Per-project data: .hoangsa/memory/ (or ~/.hoangsa/memory/projects/<slug>/)
• Shared model cache: ~/.hoangsa/cache/fastembed/ (~4xx MB on disk once warm)
• First run: hoangsa-memory init && hoangsa-memory index .

If you passed --no-embed and want to prefetch weights later:

hoangsa-memory prefetch-embed

Wraps Claude Code's Bash tool calls and trims verbose output (cargo/npm/git log/curl JSON) before the model reads it. 60–90% token savings on the noisiest commands.

• Binary: ~/.hoangsa/bin/hsp
• Global hook: hsp init — writes PreToolUse hook into ~/.claude/settings.json
• Per-project hook: hsp init -p — writes into ./.claude/settings.local.json
• Self-check: hsp doctor

Full reference: crates/hoangsa-proxy/README.md.

From a checkout of the repo:

scripts/uninstall.sh --global          # remove global install
scripts/uninstall.sh --local           # remove project-local install
scripts/uninstall.sh --global --purge  # also delete ~/.hoangsa entirely

Without --purge, the uninstaller leaves your memory data, fastembed cache, and staged templates under ~/.hoangsa/ in place — so you can reinstall without re-indexing or re-downloading model weights.

To remove a single cargo install-ed binary:

cargo uninstall hoangsa-cli
cargo uninstall hoangsa-memory
cargo uninstall hoangsa-memory-mcp
cargo uninstall hoangsa-proxy       # binary name is `hsp`

Prerequisites: the Claude Code CLI.

curl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh
/hoangsa:init        # Initialize project — detect codebase, set preferences
/hoangsa:menu        # Design your first task → DESIGN-SPEC + TEST-SPEC

After /hoangsa:menu, run /hoangsa:prepare to plan, then /hoangsa:cook to execute.

HOANGSA ships with hoangsa-memory, a local MCP server that gives Claude persistent memory (facts, lessons, preferences) and code-graph awareness (impact analysis, symbol context, change detection) across sessions.

• Auto-installed by the installer: binaries land in ~/.hoangsa/bin/ and the MCP server is registered in your project's .mcp.json.
• State per project lives under ~/.hoangsa/memory/projects/<slug>/ (MEMORY.md, LESSONS.md, USER.md + index).
• Hooks installed into Claude Code settings: pre-edit rule enforcement, pre-edit lesson recall, post-tool event logging, and PreCompact / SessionEnd archive ingest for conversation recall.
• Archive search (full conversation history) uses the in-process fastembed vector store — no sidecar required. The installer pre-downloads the multilingual-e5-small weights (~4xx MB) into ~/.hoangsa/cache/fastembed/; pass --no-embed to skip and fetch lazily on first use.

Manual reindex: /hoangsa:index or ~/.hoangsa/bin/hoangsa-memory --json index .

Config lives in .hoangsa/config.json. Manage preferences with /hoangsa:init or hoangsa-cli pref set.

Select a profile (quality / balanced / budget) to control the model at each of 8 roles. Switch with /hoangsa:init or by editing profile in config.json.

MIT — Copyright (c) 2026 Zan

Author: Zan — @pirumu

Tiếng Việt