HOANGSA

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.

Installation

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.

Supported platforms

Triple	Status	Notes
`darwin-arm64`	✅ Supported	Apple Silicon (M1 / M2 / M3 / M4)
`linux-x64`	✅ Supported	glibc-based distros (Ubuntu, Debian, Fedora, RHEL, …)
`linux-arm64`	✅ Supported	glibc-based distros
`linux-*` (musl / Alpine)	❌ Not supported	ONNX Runtime binaries link glibc — build from source
Windows	❌ Not yet	Use WSL2 (Ubuntu)

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).

Option A — release installer (recommended)

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 --):

Flag	Effect
`--global`	Install globally for this user (default) — writes to the resolved Claude config dir
`--local`	Install for the current project only — writes to `./.claude/`
`--target claude\|codex\|both`	Select the install target. Default is `claude`; `codex` configures Codex memory MCP, skills, guidance, and hooks.
`--codex-memory-root <path>`	Pin Codex memory to a specific root. Valid only with `--local --target codex` or `--local --target both`; writes only to `<project>/.codex/config.toml`.
`--no-embed`	Skip pre-downloading the `multilingual-e5-small` weights (~118 MB). They will fetch lazily on first `index` / `query` / `archive ingest`. Useful on bandwidth-constrained links.
`--dry-run`	Print actions without writing files — good for auditing
`--help`	Show the installer help

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
# Codex memory MCP only
hoangsa-cli install --target codex --global
hoangsa-cli install --target codex --local
# 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:

Variable	Default	Purpose
`HOANGSA_VERSION`	`latest`	Release tag to install (e.g. `v0.2.2`)
`HOANGSA_REPO`	`pirumu/hoangsa`	GitHub repo slug to download from
`HOANGSA_INSTALL_DIR`	`$HOME/.hoangsa`	Root for all binaries and cache
`HOANGSA_CLI_DIR`	`$HOANGSA_INSTALL_DIR/bin`	Override just the CLI bin dir
`HOANGSA_NO_PATH_EDIT`	—	Set to `1` to skip `~/.zshrc` / `~/.bashrc` edits (export PATH manually)
`CLAUDE_CONFIG_DIR`	auto-detected	Pin a specific Claude profile (`~/.claude`, `~/.zclaude`, …)

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.

Option B — build from source (contributors)

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.

Codex memory mode

Codex support uses Codex-native files instead of writing Claude-only surfaces. It does not install Claude slash commands or Claude agent templates. Codex workflow commands are installed as skills, with optional custom-prompt shortcuts for the Codex slash menu.

hoangsa-cli install --target codex --global
hoangsa-cli install --target codex --local
hoangsa-cli install --target both --local
hoangsa-cli install --target codex --local --codex-memory-root "$PWD/.hoangsa/memory"

Global Codex installs write ~/.codex/config.toml; local installs write <project>/.codex/config.toml:

[mcp_servers.hoangsa-memory]
command = "/ABSOLUTE/PATH/TO/hoangsa-memory-mcp"args = []
startup_timeout_sec = 20tool_timeout_sec = 120
[mcp_servers.hoangsa-memory.env]
RUST_LOG = "info"

Do not set global HOANGSA_MEMORY_ROOT; the MCP server resolves the right Hoangsa memory project from the Codex session working directory. Use --codex-memory-root <path> only with a local Codex install when intentionally pinning one project. The override is written only to the project-local .codex/config.toml.

Codex TOML merges preserve unrelated settings and MCP servers semantically after parse/write. They do not preserve comments or original formatting.

After installing, start Codex in the project and run /mcp to confirm that hoangsa-memory tools are listed.

The installer also routes memory skills to .agents/skills/hoangsa/, installs Codex-native command workflow skills such as $hoangsa-menu, syncs Hoangsa guidance into AGENTS.md, and writes conservative Codex hook entries under .codex/hooks.json. Global Codex installs also write managed prompt shortcuts into ~/.codex/prompts/, which Codex exposes as /prompts:hoangsa-menu style slash-menu entries. hsp shell-output rewriting is not enabled for Codex unless explicitly opted in by a later release.

Codex command examples:

$hoangsa-menu
use hoangsa menu
/prompts:hoangsa-menu

Claude Code keeps the original command shape:

/hoangsa:menu

The Codex command player can also be used directly:

hoangsa-cli codex commands --json
hoangsa-cli codex render menu --arguments "design the billing screen"
hoangsa-cli codex install-prompts --global

Codex support is intentionally scoped:

Codex installs configure memory MCP, memory skills, guidance, and project/global hook files; they do not install Claude slash commands or Claude agent templates.
Global Codex installs never write HOANGSA_MEMORY_ROOT. Local Codex installs preserve an existing project-local HOANGSA_MEMORY_ROOT when --codex-memory-root is omitted.
Hoangsa UI/API config edits are constrained to validated Hoangsa config files only: global config.json or project .hoangsa/config.json. Project paths must resolve to existing directories; selected files are rejected before registration, switching, diffing, or applying config.
Codex plugin hook bundling is not enabled yet. Direct CLI install is the supported path for Codex hooks until the Codex plugin hook schema is validated against the target Codex release.

Codex plugin package

This repo also includes a local Codex plugin package for Desktop/App testing:

plugins/hoangsa-codex/
.agents/plugins/marketplace.json

The plugin packages the Codex-safe memory skills, Codex-native Hoangsa command workflow skills, and a hoangsa-memory MCP server entry. The MCP command expects hoangsa-memory-mcp to be on PATH, usually from the release installer or a source build.

To test the repo-local marketplace:

codex plugin marketplace add .
codex plugin add hoangsa-codex@hoangsa-local

Hooks are not bundled through the plugin yet. Use hoangsa-cli install --target codex --local for full project-local Codex wiring, including hooks, until Codex plugin hook packaging is validated against the target Codex release.

Post-install: PATH and verification

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

# hoangsa:managed startexport 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

Per-CLI install notes

`hoangsa-cli` — HOANGSA orchestrator

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.

`hoangsa-memory` — long-term memory + code intelligence

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

`hsp` — CLI output compressor

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.

Uninstall

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`

Troubleshooting

Symptom	Fix
`command not found: hoangsa-cli` after install	PATH not updated in current shell. `source ~/.zshrc` or open a new terminal.
`musl libc detected` on Alpine	Release tarballs are glibc-only. Use `scripts/install-local.sh` from a checkout on Alpine — requires `rustc` + `cargo`.
MCP tools missing in Claude Code	`CLAUDE_CONFIG_DIR` mismatch. Set it explicitly before install: `CLAUDE_CONFIG_DIR=~/.zclaude curl -fsSL …\| sh`.
`vector_store failed to start` on first `index`	fastembed weights missing or corrupted. Run `hoangsa-memory prefetch-embed` or delete `~/.hoangsa/cache/fastembed/` and retry.
Installer stalls on prompt under `curl\|sh`	stdin is piped. Pass flags explicitly: `sh -s -- --global` and set `HOANGSA_NO_PATH_EDIT=1`.
`GitHub API rate limit exceeded`	Pin a tag: `HOANGSA_VERSION=v0.2.2 curl …` — skips the `/releases/latest` API call.

Quick Start

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.

Commands

Core Workflow

Command	Description
`/hoangsa:brainstorm`	Explore a vague idea → BRAINSTORM.md (feeds into menu)
`/hoangsa:menu`	Design — interview → DESIGN-SPEC + TEST-SPEC
`/hoangsa:prepare`	Plan — specs → executable task DAG (`plan.json`)
`/hoangsa:cook`	Execute — wave-by-wave, fresh context per worker task
`/hoangsa:taste`	Test — run acceptance tests per task
`/hoangsa:plate`	Commit — stage + generate conventional commit message
`/hoangsa:ship`	Ship — code + security review, then push or create PR
`/hoangsa:serve`	Sync — bidirectional sync with connected task manager
`/hoangsa:fix`	Hotfix — cross-layer root cause tracing + minimal fix
`/hoangsa:audit`	Audit — 8-dimension codebase scan (security, debt, coverage…)
`/hoangsa:research`	Research — codebase analysis + external research → RESEARCH.md

Utility

Command	Description
`/hoangsa:rule`	Rules — add, remove, or list project enforcement rules
`/hoangsa:addon`	Addons — list, add, or remove framework-specific worker rule addons
`/hoangsa:init`	Initialize — detect codebase, configure preferences, first-time setup
`/hoangsa:check`	Status — show current session progress and pending tasks
`/hoangsa:index`	Index — rebuild hoangsa-memory code intelligence graph
`/hoangsa:update`	Update — upgrade HOANGSA to the latest version
`/hoangsa:help`	Help — show all available commands

Memory & Code Intelligence

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 .

Configuration

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

Preferences

Key	Values	Description
`lang`	`en`, `vi`	Language for output
`spec_lang`	`en`, `vi`	Language for generated specs
`tech_stack`	array	Project technology stack
`review_style`	`strict`, `balanced`, `light`, `whole_document`	Code review thoroughness
`interaction_level`	`minimal`, `quick`, `standard`, `detailed`	How much the orchestrator asks
`auto_taste`	`true`, `false`	Auto-run tests after cook
`auto_plate`	`true`, `false`	Auto-commit after cook
`auto_serve`	`true`, `false`	Auto-sync to task manager

Model Profiles

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.

Role	`quality`	`balanced`	`budget`
researcher	opus	sonnet	haiku
designer	opus	opus	sonnet
planner	opus	sonnet	haiku
orchestrator	opus	opus	haiku
worker	opus	sonnet	haiku
reviewer	opus	sonnet	haiku
tester	sonnet	haiku	haiku
committer	sonnet	haiku	haiku

License

Author: Zan — @pirumu

Tiếng Việt

Name		Name	Last commit message	Last commit date
.agents/plugins		.agents/plugins
.github		.github
crates		crates
plugins/hoangsa-codex		plugins/hoangsa-codex
scripts		scripts
templates		templates
.gitignore		.gitignore
.memoryignore		.memoryignore
CHANGELOG.md		CHANGELOG.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README.vi.md		README.vi.md
rust-toolchain.toml		rust-toolchain.toml

Navigation Menu

Uh oh!

Repository files navigation

HOANGSA

Installation

Supported platforms

Option A — release installer (recommended)

Option B — build from source (contributors)

Codex memory mode

Codex plugin package

Post-install: PATH and verification

Per-CLI install notes

`hoangsa-cli` — HOANGSA orchestrator

`hoangsa-memory` — long-term memory + code intelligence

`hsp` — CLI output compressor

Uninstall

Troubleshooting

Quick Start

Commands

Core Workflow

Utility

Memory & Code Intelligence

Configuration

Preferences

Model Profiles

License

About

Releases

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

HOANGSA

Installation

Supported platforms

Option A — release installer (recommended)

Option B — build from source (contributors)

Codex memory mode

Codex plugin package

Post-install: PATH and verification

Per-CLI install notes

hoangsa-cli — HOANGSA orchestrator

hoangsa-memory — long-term memory + code intelligence

hsp — CLI output compressor

Uninstall

Troubleshooting

Quick Start

Commands

Core Workflow

Utility

Memory & Code Intelligence

Configuration

Preferences

Model Profiles

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`hoangsa-cli` — HOANGSA orchestrator

`hoangsa-memory` — long-term memory + code intelligence

`hsp` — CLI output compressor