HWCode

A customizable terminal coding agent built on Pi, with local-model providers, persistent working directories, a tailored TUI, and Vibe/SDD/Cloud workflows.

Install

HWCode requires Node.js 22.19 or newer. Install it globally from npm:

npm install --global @hadooppei/hwcode

Then start it from the project directory you want to work in:

cd your-project
hwcode

Run hwcode --help for the HWCode command reference, including model, session, tool, and workflow options.

npx @hadooppei/hwcode is also supported without a global installation. HWCode loads a project's .env file when present and keeps Pi's normal user-level auth and session storage. Project-local Pi resources continue to load alongside the built-in HWCode profile, except for HWCode's package-scoped model-provider definition described below.

Repository setup

npm install --ignore-scripts
cp .env.example .env
npm start

On first launch, review and accept Pi's project-trust prompt so it can load the resources under .pi/.

Model providers

The published .pi/model-providers.json is package-scoped and is not replaced by a file in the current project. It registers the configurable hw provider without shipping a machine-specific endpoint or a pre-populated model catalog. Use Pi's native /login flow, select Huawei MaaS, and enter the endpoint and API key. The key can instead come from HW_API_KEY. HWCode then discovers every model exposed by the OpenAI-compatible endpoint and Pi stores the selected endpoint, credential, and dynamic catalog in its user-level stores.

The published provider is equivalent to:

{
  "id": "hw",
  "name": "Huawei MaaS",
  "apiKeyEnv": "HW_API_KEY",
  "login": {
    "enabled": true,
    "promptBaseUrl": true,
    "promptApiKey": true,
    "apiKeyRequired": true,
    "catalogPath": "models"
  },
  "modelDefaults": {
    "input": ["text"],
    "contextWindow": 1000000,
    "maxTokens": 8192
  }
}

id is the stable credential and cache key; name is the configurable label shown alongside other providers in /login. A login authenticates the whole provider and publishes its complete model catalog to /model. Unknown models default to text-only. Keep real API keys in .env or enter them through /login; Pi stores entered credentials in its own auth store rather than the package configuration.

Repository maintainers can refer to .pi/model-providers.json.template for the previous local static-provider examples, including multimodal metadata. The template is not loaded at runtime and is explicitly excluded from npm packages.

Welcome screen

The responsive vector-rasterized Braille pixel logo is configured in .pi/welcome.json. logo accepts 1-6 English letters. characterColors contains Pi theme color names and cycles when fewer colors than characters are provided. The logo scales and centers itself whenever the fullscreen terminal is resized. The first submitted prompt removes the welcome UI before the conversation is rendered.

Development workflows

Start one of the project workflows from the Pi input:

/hwcode-vibe Build a small web application with me
/hwcode-sdd Add role-based access control
/hwcode-cloud Deploy this service with a managed database

Both commands first confirm the current directory and lock project work to that root for the session. In-root operations run normally; each tool call that names an external path asks for separate approval. The non-storage sink /dev/null is approval-free even when used by shell redirection. /hwcode-vibe uses short iterative build-and-verify loops. /hwcode-sdd additionally requires the current directory to be the Git repository root, inventories the codebase, resolves requirement questions, and persists approved artifacts under .hwcode/specs/<requirement-slug>/ before test-first implementation begins. SDD phases are persisted and advance one step at a time through an interactive approval gate. Before the tests phase, built-in file writes are restricted to the spec directory; production writes begin only in implementation.

Use /hwcode to inspect, complete, or cancel the active workflow. Completing SDD is allowed only after verification. Cloud completion warns about any workflow-created resources that remain active in its resource inventory.

Cloud workflow

/hwcode-cloud interactively collects the cloud provider, whether the current project should be deployed, and the concrete objective. It supports AWS, Azure, Google Cloud, Huawei Cloud, Alibaba Cloud, and Tencent Cloud. Provider-specific credentials are entered through masked prompts and validated before planning.

Credentials are encrypted with AES-256-GCM using a key derived from a user master password and stored at ~/.hwcode/cloud/credentials.enc with user-only permissions. They are never added to model context or uploaded to an HWCode service. Authentication necessarily sends them to the selected provider's official endpoint or CLI. Google credential JSON is materialized only in a user-only temporary file for the duration of a command. Azure CLI authentication uses an isolated temporary configuration directory that is removed after each command.

Multiple credential profiles can be saved for the same provider. On the next Cloud workflow, HWCode offers each existing profile as 使用已有凭据 [n] · Region: <region> plus 新建凭据; only the region and an ordinal are displayed. Legacy vaults containing one credential per provider are migrated in memory and written in the multi-profile format after the next successful validation.

Cloud and infrastructure commands run through a credential-isolated tool. Read-only calls run directly. Account-resource creates and changes require user confirmation unless the user approves remaining non-delete changes for the session. Resource deletion is always confirmed. After three genuinely distinct technical approaches fail, the workflow stops and reports causes, progress, remaining resources, and local changes instead of attempting a fourth approach. Read-only inspection and confirmed cleanup deletion remain available after the failure budget is reached.

Terraform execution uses a pinned SSH Runner connection. New and existing hosts share the same OpenSSH SHA256 host-key confirmation path; private targets can be scanned through a verified ProxyJump. Runner execution requires Terraform, tar, sha256sum, a declared cloud workload identity, and an explicit non-local Terraform backend. The exact policy-checked file manifest is uploaded and its per-file digest is verified remotely before execution.

Knowledge capture is independent from workflow and session completion. Every HWCode process owns a lightweight Worker, but a user-private Unix socket elects exactly one machine-local Leader. The Leader checks every open or closed session once per minute and serially asks its configured model to review uncommitted session deltas. Workers without model access remain ineligible; they rejoin the election automatically after model authentication becomes available.

Reusable knowledge is stored as immutable generations under ~/.hwcode/knowledge-v3/ using two tracks. Short, high-confidence rules live under each generation's rules/ directory and every applicable rule is loaded when an agent starts. Detailed SOPs and evolving engineering experience live under topics/; only the bounded keyword index is loaded into the prompt. The hwcode_knowledge_lookup tool loads a detailed topic on demand. A generation atomically publishes rules, topics, the complete catalog, and per-session review cursors, so a catalog can never reference an unpublished body. Exact repeats are reinforced, safe explicit revisions replace their source, and ambiguous conflicts are quarantined under pending/. Earlier knowledge layouts are neither loaded nor migrated.

A successful managed Terraform apply additionally produces a schema-v2 Terraform Template bundle containing filtered Terraform, Helm, discovery and report artifacts plus verification notes, exclusion reasons, and content/metadata integrity digests. Bundles are stored under ~/.hwcode/cloud/templates/terraform/ with user-only permissions; credential values are excluded and redacted before artifacts are persisted. A successful managed apply automatically creates a new bundle, or atomically updates the source bundle when the run started from one. /hwcode-cloud offers saved bundles when it starts without an inline request. Bundles remain extension-private executable artifacts, separate from the knowledge base, and reuse always goes through the normal Cloud credential isolation and approval guards.

Internal architecture

Extensions under .pi/extensions/ are Pi-facing adapters: they register events, commands, tools, and UI. extensions/workflows.ts is the single Workflow entry; Vibe/SDD live in extensions/workflows/vibe-sdd.ts, while the Cloud adapter is split under extensions/workflows/cloud/ into activation, commands, events, Provider tools, Runner tools, Terraform tools, shared UI, and session runtime. Reusable behavior lives under .pi/lib/:

• runtime/ owns layered/replacing configuration, canonical runtime paths, and session-state primitives.
• workflows/ owns the shared lifecycle schema; workflows/cloud/ contains the complete Cloud workflow domain, including its remote/ and terraform/ execution components.
• workspace/ owns tool and command path-boundary decisions.
• context/ and models/ own compaction and provider-configuration policy.

Runtime data is separated by ownership: project SDD specifications live under .hwcode/specs/, retained Cloud run artifacts live under .hwcode/cloud/runs/<run-id>/, user-private credentials, SSH trust, and Terraform Templates live under ~/.hwcode/cloud/, and the cross-workflow knowledge base lives under ~/.hwcode/knowledge-v3/. Cloud run artifacts are deliberately retained for inspection and automatic bundle extraction; HWCode does not apply a time-based cleanup policy.

settings.json is layered as defaults → profile → project for settings such as context and hidden commands. welcome.json uses a single replacing resource. model-providers.json is deliberately package-scoped so a project cannot silently replace login providers or reintroduce machine-local defaults.

Working directory

Use /cd <path> to change the working directory without starting a new session. A leading cd in either an agent shell call or a user ! shell command has the same persistent behavior. Subsequent shell commands, built-in file tools, the Footer, and workflow activation all use the updated directory. The directory is stored in the session and restored when that session resumes; cd - returns to its previous directory. An active HWCode workflow keeps its directory lock and rejects changes to another root.

Command visibility

The hwcode.hiddenCommands array in .pi/settings.json removes selected commands from slash-command autocomplete. Store names without the leading /; skill commands use names such as skill:hwcode-vibe. An empty array shows every command. Restart Pi or manually enter /reload after changing the list.

This setting controls visibility, not capability. A hidden command can still be entered manually when it is needed.

Context and compaction

HWCode defaults locally configured and dynamically discovered models to a 1,000,000-token context window and caps configured or provider-reported values at that limit. If an OpenAI-compatible model catalog reports a smaller context_window, context_length, max_context_length, max_model_len, or n_ctx, the smaller server value wins. The package-scoped provider's modelDefaults.contextWindow can also select a smaller limit for dynamically discovered models.

The default context policy is configured under hwcode.context in .pi/settings.json:

{
  "compaction": {
    "enabled": true,
    "reserveTokens": 80000,
    "keepRecentTokens": 220000
  },
  "hwcode": {
    "context": {
      "defaultContextWindow": 1000000,
      "maxContextWindow": 1000000,
      "compactionTriggerTokens": 920000,
      "compactionTargetTokens": 300000,
      "compactionOverheadTokens": 80000
    }
  }
}

For a 1M model, HWCode starts compaction around 920K and retains up to 220K of recent messages, reserving 80K for the system prompt, tools, and summary so the result remains within the 300K target. The policy scales proportionally for smaller models. A single indivisible message larger than the target cannot be silently truncated; HWCode keeps it and displays a warning instead.

Project resources

• AGENTS.md: project-wide working rules
• .pi/settings.json: project-level Pi settings
• .pi/APPEND_SYSTEM.md: additions to the system prompt
• .pi/extensions/: TypeScript extensions
• .pi/skills/: reusable workflows
• .pi/prompts/: slash-command prompt templates

Credentials must not be committed. Use environment variables or Pi's user-level authentication store.