{"id":48891309,"url":"https://github.com/unknown-studio-dev/hoangsa","last_synced_at":"2026-04-24T05:01:30.786Z","repository":{"id":344516190,"uuid":"1177935235","full_name":"unknown-studio-dev/hoangsa","owner":"unknown-studio-dev","description":"HOANGSA is a context engineering system for Claude Code. It solves a fundamental problem: Claude's output quality degrades as the context window fills up.","archived":false,"fork":false,"pushed_at":"2026-04-19T17:20:53.000Z","size":358,"stargazers_count":18,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-19T19:33:49.980Z","etag":null,"topics":["claude","claude-code","context-engineering","meta-prompting","spec-driven-development"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unknown-studio-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-10T14:20:33.000Z","updated_at":"2026-04-19T17:20:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/unknown-studio-dev/hoangsa","commit_stats":null,"previous_names":["pirumu/hoangsa","unknown-studio-dev/hoangsa"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/unknown-studio-dev/hoangsa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown-studio-dev%2Fhoangsa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown-studio-dev%2Fhoangsa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown-studio-dev%2Fhoangsa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown-studio-dev%2Fhoangsa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unknown-studio-dev","download_url":"https://codeload.github.com/unknown-studio-dev/hoangsa/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unknown-studio-dev%2Fhoangsa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32209895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T03:15:14.334Z","status":"ssl_error","status_checked_at":"2026-04-24T03:15:11.608Z","response_time":64,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claude-code","context-engineering","meta-prompting","spec-driven-development"],"created_at":"2026-04-16T08:04:08.405Z","updated_at":"2026-04-24T05:01:30.771Z","avatar_url":"https://github.com/unknown-studio-dev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HOANGSA\n\n\u003e A context engineering system for Claude Code\n\n![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)\n![Claude Code](https://img.shields.io/badge/Claude_Code-compatible-blueviolet.svg)\n![Built with Rust](https://img.shields.io/badge/Built_with-Rust-orange.svg)\n\n---\n\nHOANGSA is a context engineering system for [Claude Code](https://docs.anthropic.com/en/docs/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.\n\n---\n\n## Installation\n\nHOANGSA ships four binaries: three CLIs you invoke directly\n(`hoangsa-cli`, `hoangsa-memory`, `hsp`) plus one MCP server\n(`hoangsa-memory-mcp`) that Claude Code spawns on your behalf.\n\n### Supported platforms\n\n| Triple | Status | Notes |\n|--------|--------|-------|\n| `darwin-arm64` | ✅ Supported | Apple Silicon (M1 / M2 / M3 / M4) |\n| `linux-x64` | ✅ Supported | glibc-based distros (Ubuntu, Debian, Fedora, RHEL, …) |\n| `linux-arm64` | ✅ Supported | glibc-based distros |\n| `linux-*` (musl / Alpine) | ❌ Not supported | ONNX Runtime binaries link glibc — build from source |\n| Windows | ❌ Not yet | Use WSL2 (Ubuntu) |\n\nPrerequisites on the target machine: `curl` or `wget`, `tar`, and one of\n`sha256sum` / `shasum`. No Node, no Python, no Docker, no `cargo` needed\nfor the release tarball.\n\nFor contributors building from source you additionally need **Rust 1.91+**\n(`rustup toolchain install stable`) and a C toolchain (`build-essential`\non Debian/Ubuntu, Xcode Command Line Tools on macOS).\n\n---\n\n### Option A — release installer (recommended)\n\nOne command pulls the latest release, verifies the SHA-256 checksum,\ndrops all four binaries into `~/.hoangsa/bin/`, registers the\n`hoangsa-memory` MCP server in Claude Code, and pre-downloads the\nfastembed ONNX weights.\n\n```sh\ncurl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh\n```\n\n**Flags** (pass after `sh -s --`):\n\n| Flag | Effect |\n|------|--------|\n| `--global` | Install globally for this user (default) — writes to the resolved Claude config dir |\n| `--local` | Install for the current project only — writes to `./.claude/` |\n| `--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. |\n| `--dry-run` | Print actions without writing files — good for auditing |\n| `--help` | Show the installer help |\n\n**Examples:**\n\n```sh\n# Global install (default)\ncurl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh\n\n# Project-local install\ncurl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh -s -- --local\n\n# Dry-run to see what would happen\ncurl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh -s -- --dry-run\n\n# Pin a specific version\nHOANGSA_VERSION=v0.2.2 curl -fsSL https://github.com/pirumu/hoangsa/releases/download/v0.2.2/install.sh | sh\n```\n\n**Environment overrides:**\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `HOANGSA_VERSION` | `latest` | Release tag to install (e.g. `v0.2.2`) |\n| `HOANGSA_REPO` | `pirumu/hoangsa` | GitHub repo slug to download from |\n| `HOANGSA_INSTALL_DIR` | `$HOME/.hoangsa` | Root for all binaries and cache |\n| `HOANGSA_CLI_DIR` | `$HOANGSA_INSTALL_DIR/bin` | Override just the CLI bin dir |\n| `HOANGSA_NO_PATH_EDIT` | — | Set to `1` to skip `~/.zshrc` / `~/.bashrc` edits (export PATH manually) |\n| `CLAUDE_CONFIG_DIR` | auto-detected | Pin a specific Claude profile (`~/.claude`, `~/.zclaude`, …) |\n\nThe installer honours `CLAUDE_CONFIG_DIR` if it is already set, and\notherwise detects multiple Claude profile dirs (`~/.claude`,\n`~/.zclaude`, …). With more than one it prompts; pass the env var\nexplicitly in non-TTY installs.\n\n---\n\n### Option B — build from source (contributors)\n\nClone the repo and run the local install helper — builds the workspace\nin release mode, installs the four binaries, and wires Claude Code the\nsame way the release installer does:\n\n```sh\ngit clone https://github.com/pirumu/hoangsa.git\ncd hoangsa\nscripts/install-local.sh --global     # or --local for per-project\n```\n\nFlags: `--global` / `--local`, `--dry-run`, `--no-embed`, `--skip-build`\n(re-run the post-build steps without recompiling).\n\n**Just one CLI?** Each binary can be installed standalone via `cargo`:\n\n```sh\ncargo install --path crates/hoangsa-cli       # installs `hoangsa-cli`\ncargo install --path crates/hoangsa-memory    # installs `hoangsa-memory`\ncargo install --path crates/hoangsa-memory-mcp # installs `hoangsa-memory-mcp`\ncargo install --path crates/hoangsa-proxy     # installs `hsp`\n```\n\nThis drops binaries into `~/.cargo/bin/`. Note that `cargo install`\nalone **does not** register MCP servers, copy templates, or wire Claude\nCode hooks — run `hoangsa-cli install --global` afterwards to finish\nsetup.\n\n---\n\n### Post-install: PATH and verification\n\nThe installer appends a managed block to the first existing rc file it\nfinds (`~/.zshrc` → `~/.bashrc`) containing:\n\n```sh\n# hoangsa:managed start\nexport PATH=\"$HOME/.hoangsa/bin:$PATH\"\n# hoangsa:managed end\n```\n\n**If the block was skipped** (non-TTY install, declined prompt,\n`HOANGSA_NO_PATH_EDIT=1`, no rc file found), add it yourself:\n\n```sh\necho 'export PATH=\"$HOME/.hoangsa/bin:$PATH\"' \u003e\u003e ~/.zshrc\nsource ~/.zshrc\n```\n\n**Verify the install:**\n\n```sh\nhoangsa-cli --version          # e.g. hoangsa-cli 0.2.2\nhoangsa-memory --version       # e.g. hoangsa-memory 0.2.2\nhoangsa-memory-mcp --version   # e.g. hoangsa-memory-mcp 0.2.2\nhsp --version                  # e.g. hsp 0.2.2\n```\n\nThen run the per-CLI self-checks:\n\n```sh\nhsp doctor                     # verifies hsp hooks + handlers\nhoangsa-memory memory show     # prints MEMORY.md + LESSONS.md for cwd\n```\n\n---\n\n### Per-CLI install notes\n\n#### `hoangsa-cli` — HOANGSA orchestrator\n\nDrives the `/hoangsa:*` slash commands, owns the rule engine, wires\nClaude Code hooks, manages project preferences.\n\n- **Binary location:** `~/.hoangsa/bin/hoangsa-cli`\n- **Per-project config:** `.hoangsa/config.json` (created by\n  `hoangsa-cli install --local` or `/hoangsa:init`)\n- **Templates:** staged to `~/.hoangsa/templates/` on global install\n- **First-run setup:** `/hoangsa:init` from inside Claude Code, or\n  `hoangsa-cli install --local` from the shell\n\nNo separate install step — bundled with the release installer.\n\n#### `hoangsa-memory` — long-term memory + code intelligence\n\nIndexes your source tree, serves recall queries, runs blast-radius\nanalysis, and manages the verbatim conversation archive.\n\n- **Binary:** `~/.hoangsa/bin/hoangsa-memory`\n- **Companion daemon:** `~/.hoangsa/bin/hoangsa-memory-mcp` (spawned by\n  Claude Code via MCP — you never start it manually)\n- **Per-project data:** `.hoangsa/memory/` (or `~/.hoangsa/memory/projects/\u003cslug\u003e/`)\n- **Shared model cache:** `~/.hoangsa/cache/fastembed/`\n  (~4xx MB on disk once warm)\n- **First run:** `hoangsa-memory init \u0026\u0026 hoangsa-memory index .`\n\nIf you passed `--no-embed` and want to prefetch weights later:\n\n```sh\nhoangsa-memory prefetch-embed\n```\n\n#### `hsp` — CLI output compressor\n\nWraps Claude Code's Bash tool calls and trims verbose output\n(cargo/npm/git log/curl JSON) before the model reads it. 60–90% token\nsavings on the noisiest commands.\n\n- **Binary:** `~/.hoangsa/bin/hsp`\n- **Global hook:** `hsp init` — writes PreToolUse hook into\n  `~/.claude/settings.json`\n- **Per-project hook:** `hsp init -p` — writes into\n  `./.claude/settings.local.json`\n- **Self-check:** `hsp doctor`\n\nFull reference: [`crates/hoangsa-proxy/README.md`](crates/hoangsa-proxy/README.md).\n\n---\n\n### Uninstall\n\nFrom a checkout of the repo:\n\n```sh\nscripts/uninstall.sh --global          # remove global install\nscripts/uninstall.sh --local           # remove project-local install\nscripts/uninstall.sh --global --purge  # also delete ~/.hoangsa entirely\n```\n\nWithout `--purge`, the uninstaller leaves your memory data, fastembed\ncache, and staged templates under `~/.hoangsa/` in place — so you can\nreinstall without re-indexing or re-downloading model weights.\n\nTo remove a single `cargo install`-ed binary:\n\n```sh\ncargo uninstall hoangsa-cli\ncargo uninstall hoangsa-memory\ncargo uninstall hoangsa-memory-mcp\ncargo uninstall hoangsa-proxy       # binary name is `hsp`\n```\n\n---\n\n### Troubleshooting\n\n| Symptom | Fix |\n|---------|-----|\n| `command not found: hoangsa-cli` after install | PATH not updated in current shell. `source ~/.zshrc` or open a new terminal. |\n| `musl libc detected` on Alpine | Release tarballs are glibc-only. Use `scripts/install-local.sh` from a checkout on Alpine — requires `rustc` + `cargo`. |\n| MCP tools missing in Claude Code | `CLAUDE_CONFIG_DIR` mismatch. Set it explicitly before install: `CLAUDE_CONFIG_DIR=~/.zclaude curl -fsSL …\\| sh`. |\n| `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. |\n| Installer stalls on prompt under `curl\\|sh` | stdin is piped. Pass flags explicitly: `sh -s -- --global` and set `HOANGSA_NO_PATH_EDIT=1`. |\n| `GitHub API rate limit exceeded` | Pin a tag: `HOANGSA_VERSION=v0.2.2 curl …` — skips the `/releases/latest` API call. |\n\n---\n\n## Quick Start\n\nPrerequisites: the **[Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code)**.\n\n```bash\ncurl -fsSL https://github.com/pirumu/hoangsa/releases/latest/download/install.sh | sh\n/hoangsa:init        # Initialize project — detect codebase, set preferences\n/hoangsa:menu        # Design your first task → DESIGN-SPEC + TEST-SPEC\n```\n\nAfter `/hoangsa:menu`, run `/hoangsa:prepare` to plan, then `/hoangsa:cook` to execute.\n\n---\n\n## Commands\n\n### Core Workflow\n\n| Command | Description |\n|---------|-------------|\n| `/hoangsa:brainstorm` | Explore a vague idea → BRAINSTORM.md (feeds into menu) |\n| `/hoangsa:menu` | Design — interview → DESIGN-SPEC + TEST-SPEC |\n| `/hoangsa:prepare` | Plan — specs → executable task DAG (`plan.json`) |\n| `/hoangsa:cook` | Execute — wave-by-wave, fresh context per worker task |\n| `/hoangsa:taste` | Test — run acceptance tests per task |\n| `/hoangsa:plate` | Commit — stage + generate conventional commit message |\n| `/hoangsa:ship` | Ship — code + security review, then push or create PR |\n| `/hoangsa:serve` | Sync — bidirectional sync with connected task manager |\n| `/hoangsa:fix` | Hotfix — cross-layer root cause tracing + minimal fix |\n| `/hoangsa:audit` | Audit — 8-dimension codebase scan (security, debt, coverage…) |\n| `/hoangsa:research` | Research — codebase analysis + external research → RESEARCH.md |\n\n### Utility\n\n| Command | Description |\n|---------|-------------|\n| `/hoangsa:rule` | Rules — add, remove, or list project enforcement rules |\n| `/hoangsa:addon` | Addons — list, add, or remove framework-specific worker rule addons |\n| `/hoangsa:init` | Initialize — detect codebase, configure preferences, first-time setup |\n| `/hoangsa:check` | Status — show current session progress and pending tasks |\n| `/hoangsa:index` | Index — rebuild hoangsa-memory code intelligence graph |\n| `/hoangsa:update` | Update — upgrade HOANGSA to the latest version |\n| `/hoangsa:help` | Help — show all available commands |\n\n---\n\n## Memory \u0026 Code Intelligence\n\nHOANGSA 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.\n\n- **Auto-installed** by the installer: binaries land in `~/.hoangsa/bin/` and the MCP server is registered in your project's `.mcp.json`.\n- **State** per project lives under `~/.hoangsa/memory/projects/\u003cslug\u003e/` (MEMORY.md, LESSONS.md, USER.md + index).\n- **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.\n- **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.\n\nManual reindex: `/hoangsa:index` or `~/.hoangsa/bin/hoangsa-memory --json index .`\n\n---\n\n## Configuration\n\nConfig lives in `.hoangsa/config.json`. Manage preferences with `/hoangsa:init` or `hoangsa-cli pref set`.\n\n### Preferences\n\n| Key | Values | Description |\n|-----|--------|-------------|\n| `lang` | `en`, `vi` | Language for output |\n| `spec_lang` | `en`, `vi` | Language for generated specs |\n| `tech_stack` | array | Project technology stack |\n| `review_style` | `strict`, `balanced`, `light`, `whole_document` | Code review thoroughness |\n| `interaction_level` | `minimal`, `quick`, `standard`, `detailed` | How much the orchestrator asks |\n| `auto_taste` | `true`, `false` | Auto-run tests after cook |\n| `auto_plate` | `true`, `false` | Auto-commit after cook |\n| `auto_serve` | `true`, `false` | Auto-sync to task manager |\n\n### Model Profiles\n\nSelect 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`.\n\n| Role | `quality` | `balanced` | `budget` |\n|------|-----------|------------|----------|\n| researcher | opus | sonnet | haiku |\n| designer | opus | opus | sonnet |\n| planner | opus | sonnet | haiku |\n| orchestrator | opus | opus | haiku |\n| worker | opus | sonnet | haiku |\n| reviewer | opus | sonnet | haiku |\n| tester | sonnet | haiku | haiku |\n| committer | sonnet | haiku | haiku |\n\n---\n\n## License\n\n[MIT](LICENSE) — Copyright (c) 2026 Zan\n\n**Author:** Zan — [@pirumu](https://github.com/pirumu)\n\n---\n\n[Tiếng Việt](README.vi.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funknown-studio-dev%2Fhoangsa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funknown-studio-dev%2Fhoangsa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funknown-studio-dev%2Fhoangsa/lists"}