用我们的确定性,对抗世界的熵增;用我们的协作,定义未来的形状。Hex4Code 是面向工业级软件工程的AI编码助手,深度适配嵌入式、半导体、系统软件等重工业场景。原生对接 Makefile、CMake 构建体系,内置全流程研发流水线引擎,结构化解析编译与测试问题,支持多语言深度集成,覆盖CLI与VS Code全场景智能编码。
| Files | Last commit | Last update |
|---|---|---|
| 4 months ago | ||
| 5 months ago | ||
| 4 months ago | ||
| 4 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 5 months ago | ||
| 4 months ago | ||
| 4 months ago | ||
| 4 months ago | ||
| 5 months ago | ||
| 4 months ago |
_ _ _ _ __ | | | |_____ ___ __ _| | _| |/ _| | |_| / _ \ \/ / '__| | | | | | |_ | _ | __/> <| | | | |_| | _| |_| |_|\___/_/\_\_| |_|\___/|_|
AI Coding Assistant Framework — Pipeline Engine · Multi-Model Routing · Ternary Compression
简体中文 · English
Features · HEX4 Tech · Domestic Platforms · Quick Start · Configuration · Architecture · Development · Contributing
With our certainty, we counter the world's entropy.
With our collaboration, we define the shape of the future.
Hex4Code is an AI coding assistant framework. Give it a natural language task, and it will orchestrate a pipeline — build code, run tests, index your codebase, manage versions — all autonomously.
You can embed it into your toolchain (core engine SDK), use it interactively in the terminal (CLI), or chat with it directly in VS Code (extension). Supports any OpenAI-compatible model including DeepSeek, OpenAI, Qwen, and more.
HEX4 Technology System
HEX4 is a technology system based on Ternary encoding (Trit) and Tropical Calculus, comprising three layers:
| Layer | Technology | Purpose |
|---|---|---|
| Encoding | Trit (Ternary) | Three-valued cells (T0/T1/T2) replace binary as the underlying data representation |
| Compression | DualTrit | Packs Trit values and TC states into 4-bit dual bytes, achieving ~44% compression ratio |
| Propagation | TC Trust Propagation | Seven-state tropical semi-ring operations that propagate confidence markers across tool call chains |
These three layers form a complete technology stack — from encoding to compression to trust evaluation — with Trit as the data foundation, DualTrit for efficient compression, and TC propagation attaching traceable certainty metrics to every operation.
Features
Pipeline Engine
Built-in development pipeline that chains the full coding workflow:
| Stage | Capability |
|---|---|
| Build | Auto-detect project type and compile |
| Test | Run tests and parse results, auto-diagnose failures |
| CodeIndex | Index codebase for symbol search and reference tracing |
| Git | Git operations, auto-commit, checkpoints, diff view |
Supports two agent modes: Pipeline mode (step-by-step execution) and General mode (freeform conversation).
Built-in Tools
11 built-in tools covering the full development workflow:
File & Shell: read, write, edit, bash
Pipeline: build, test, git, code-index
Interaction & Search: web-search, ask-user-question
Multi-Model Routing
Automatically selects the optimal model based on task type:
| Provider | ID | Notes |
|---|---|---|
| DeepSeek | deepseek |
Context Caching + Thinking Mode, default provider |
| OpenAI | openai |
Standard OpenAI-compatible API, multimodal |
| Qwen | qwen |
Alibaba Cloud, strong Chinese understanding |
| Gemini | gemini |
Google, million-token context window |
| ERNIE | ernie |
Baidu Qianfan platform |
| MiniMax | minimax |
Cost-effective completions |
| GLM | glm |
Tsinghua, supports Thinking Mode |
| Anthropic | anthropic |
Claude, leading code generation and reasoning |
| Groq | groq |
Ultra-low latency, open-source model hosting |
| Mistral | mistral |
Codestral FIM completions |
| Custom | custom |
Any OpenAI-compatible API |
Semantic Cache
Automatically caches similar LLM responses, reducing duplicate API calls and saving token costs.
Ternary Compression (DualTrit)
Hex4Code's proprietary context compression algorithm — efficiently compresses conversation history using ternary encoding, extending the effective dialogue window within the same token budget.
RAG Knowledge Base
Retrieval-augmented generation based on project code — automatically indexes code structure and retrieves relevant code snippets as context during conversations.
MCP Protocol
Supports the Model Context Protocol standard for integrating external tools such as GitHub, databases, and custom APIs.
Skills System
Supports user-level (~/.agents/skills/) and project-level (./.agents/skills/) skill directories, using Markdown files to extend custom instructions.
Session Management
Every conversation is auto-saved locally. Use /resume to restore previous sessions, /new to start a fresh conversation, and /exit to quit. Session data is isolated by project directory.
Version Updates
Automatically checks for the latest npm version on startup and prompts in the TUI when an update is available. Update with npm update -g @hex4code/cli.
Safety
- Sensitive operations require confirmation before execution
- Path access outside the workspace triggers automatic approval
- API Keys are isolated per Provider, never shared across vendors
Domestic Platform Support
Hex4Code has been verified end-to-end on the following domestic computing platforms, covering Node.js / TypeScript toolchain compilation and deployment, CLI and TUI interaction, and full core engine operation (ternary + TC four-state computing):
| Platform | Architecture | Operating System | Status |
|---|---|---|---|
| Sophon (算能 / SOPHGO) | RISC-V / ARM | Sophon Linux | ✅ |
| Sunway (申威) | SW-64 | Sunway-custom Linux (Deepin / EulerOS) | ✅ |
| Phytium (飞腾) | ARMv8 | Kylin V10 / UOS 20 | ✅ |
| Hygon (海光) | x86_64 | Kylin V10 / UOS 20 / Mainstream Linux | ✅ |
| Kunpeng (鲲鹏) | ARMv8 | Kylin V10 / openEuler | ✅ |
| Zhaoxin (兆芯) | x86_64 | Kylin V10 / UOS 20 / Mainstream Linux | ✅ |
| LoongArch (龙芯) | LoongArch | Loongson Linux / Kylin V10 | ✅ |
More platforms are being continuously adapted. For support on specific domestic platforms, please contact us or submit an Issue.
Project Structure
hex4_code_v1.1/
├── packages/
│ ├── core/ # Core engine (sessions, routing, cache, pipeline)
│ │ └── src/ # TypeScript source
│ └── cli/ # Terminal TUI app (React/Ink)
│ └── src/ # React source
├── vscode/ # VS Code extension
│ ├── src/ # Extension source
│ └── resources/ # WebView UI
├── AGENTS.md # Project instructions
├── LICENSE # Apache-2.0 license
├── NOTICE # Copyright notice
├── package.json # Root workspace config
└── tsconfig.base.json # Shared TypeScript config
Quick Start
Requirements
- Node.js >= 18
- npm >= 9
1. Clone
git clone https://atomgit.com/zzwgbdt/Hex4Code.git
cd Hex4Code
2. Install & Build
npm install
npm run build
Build outputs:
- CLI →
packages/cli/dist/cli.js - VS Code →
vscode/out/extension.js
3. Run
# Development mode
npx tsx packages/cli/src/cli.tsx
# Or run the compiled version
node packages/cli/dist/cli.js
4. Install VS Code Extension
code --install-extension vscode/hex4code-vscode-1.1.0.vsix
See docs/packaging.md for packaging details.
AI Assisted Installation
If you use AI coding tools like CodeBuddy, Cursor, or Windsurf, you can have the AI handle Hex4Code's installation and configuration for you.
Step 1: Let AI Scan the Project
Open the downloaded Hex4Code project folder in your AI tool and ask it to read the structure:
"Please scan this Hex4Code project and tell me its structure and purpose."
The AI will recognize this is a TypeScript monorepo with three packages: core (engine), cli (terminal app), and vscode (VS Code extension).
Step 2: Let AI Install the VS Code Extension
Ask the AI to install the VS Code extension:
"Please install the VS Code extension from this project into my IDE. The extension is in the vscode/ directory. First run npm run build:vscode to compile, then run code --install-extension vscode/hex4code-vscode-1.1.0.vsix."
The AI will execute the build and installation commands.
Step 3: Configure the API Manually
Open the chat interface, click the gear-shaped settings button in the top right corner, select any model provider (e.g. DeepSeek) from the popup window, and enter your API key in the input field.
Usage
CLI Mode
hex4code # Launch TUI
hex4code --help # View help
hex4code --version # View version
Start typing natural language commands:
> Analyze the code structure of this project
> Add error handling to all API endpoints
> Run tests and fix failing cases
Keybindings
| Key | Action |
|---|---|
Enter |
Send message |
Shift+Enter |
New line |
Alt+Left/Right |
Move by word |
Home/End |
Move to start/end of line |
Ctrl+W |
Delete previous word |
Ctrl+V |
Paste image from clipboard |
Ctrl+X |
Clear pasted images |
Esc |
Interrupt model output |
Up/Down |
Browse input history |
Ctrl+C (twice) |
Quit application |
/ |
Open skills/commands menu |
Pasting images on Windows: Windows Terminal and conhost may intercept
Ctrl+V. If pasting images doesn't work, try pasting via the/menu.
Slash Commands
| Command | Description |
|---|---|
/new |
Start a new conversation |
/init |
Initialize project workflow |
/resume |
Resume previous session |
/compact |
Compress session context |
/config |
Show current configuration |
/context |
Show context usage |
/cost |
Show token cost statistics |
/doctor |
Run diagnostic check |
/memory |
Manage long-term memory |
/status |
Show connection status |
/exit |
Quit application |
Project Instructions (AGENTS.md)
Run /init in the project root to generate an AGENTS.md file that provides project-level context to the AI. Edit this file to add project descriptions, coding conventions, etc. The AI will read and follow them automatically:
# Project Instructions
This is a Vue 3 + TypeScript project using Composition API.
- Use TailwindCSS for styling
- Run `npm run lint` to check code style
You can also create AGENTS.md manually.
VS Code Mode
After installing the extension, a Hex4Code icon appears in the sidebar. Click it to open the chat panel (WebView) and start typing natural language instructions. The currently open editor content is automatically attached as context.
Configuration
Minimal Configuration
{
"model": "deepseek-chat",
"thinkingEnabled": true,
"reasoningEffort": "max",
"providers": {
"deepseek": {
"apiKey": "sk-...",
"baseURL": "https://api.deepseek.com"
}
}
}
Custom Model Endpoints
Mount multiple custom API endpoints under the same Provider, each with its own URL, key, and model list:
{
"providers": {
"deepseek": {
"apiKey": "sk-main",
"endpoints": [
{
"id": "local-inference",
"name": "Local Inference",
"baseURL": "http://localhost:8000/v1",
"compatibility": "openai-compatible",
"models": ["local-model-v1", "local-model-v2"]
},
{
"id": "proxy-service",
"name": "Third-Party Proxy",
"baseURL": "https://my-proxy.example.com/v1",
"apiKey": "sk-proxy",
"models": ["gpt-4o", "claude-sonnet"]
}
]
}
}
}
Field descriptions:
| Field | Description |
|---|---|
id |
Endpoint unique identifier |
name |
Display name (optional) |
baseURL |
API address |
apiKey |
Endpoint-specific key (optional, inherits from Provider level if not set) |
compatibility |
Compatibility mode: "openai-compatible" / "minimax" / "ollama" |
models |
List of available model names for this endpoint |
Non-Standard Provider Access
For non-standard OpenAI-compatible services like Ollama, specify compatibility and models:
{
"providers": {
"ollama": {
"baseURL": "http://localhost:11434/v1",
"compatibility": "ollama",
"models": ["llama3", "qwen2"]
}
}
}
Configuration Priority
Environment variables HEX4CODE_*
> Project level ./.hex4code/settings.json
> User level ~/.hex4code/settings.json
> Default values
Environment Variables
| Variable | Description |
|---|---|
HEX4CODE_API_KEY |
API key |
HEX4CODE_BASE_URL |
API endpoint URL |
HEX4CODE_MODEL |
Default model |
HEX4CODE_PROVIDER |
Default provider |
Full configuration reference (detailed options, multi-model routing, MCP servers, Skills config) see docs/configuration.md.
Architecture
packages/core/ ← Core engine (no UI dependency)
├── models/ Model routing, Provider clients
├── cache/ Semantic cache
├── compression/ Ternary compression (DualTrit)
├── orchestration/ Pipeline orchestration
├── tc/ TC propagation
├── mcp/ MCP protocol
├── tools/ Built-in tools
└── session/ Session management
packages/cli/ ← Terminal TUI (React/Ink)
├── ui/ UI components
└── cli.tsx Entry point
vscode/ ← VS Code extension
├── src/ Extension logic
└── resources/ WebView frontend
Design Principles
- Engine-agnostic — core package has no UI dependency; CLI and VS Code share the same core
- Pipeline-first — build → test → index → version management development loop
- Model-neutral — connect to any OpenAI-compatible API via the Provider adapter layer
- Context-efficient — DualTrit compression + semantic cache + RAG working together
Testing
# Run all tests
npm test
# Run individual package tests
npm run test:core
npm run test:cli
npm run test:vscode
Uses Node.js native test runner (tsx --test).
See packages/core/src/tests/README.md for notes on test coverage.
Development
# Type checking
npm run typecheck
# Code linting & formatting
npm run lint # ESLint check
npm run lint:fix # Auto-fix
npm run format # Prettier formatting
npm run check # Typecheck + lint + format check
# Build
npm run build
# Run CLI in development mode
npx tsx packages/cli/src/cli.tsx
# Build CLI only
npm run build:cli
Contributing
Contributions are welcome! Please follow these steps:
- Fork this repository
- Clone:
git clone https://atomgit.com/<your-username>/Hex4Code.git - Create a branch:
git checkout -b feat/xxxorfix/xxx - Make changes, ensure
npm run typecheckpasses - Commit:
git commit -m "feat: add xxx" - Push and open a Pull Request
Branch Naming
| Prefix | Purpose |
|---|---|
feat/ |
New feature |
fix/ |
Bug fix |
refactor/ |
Refactoring (no behavior change) |
docs/ |
Documentation |
chore/ |
Build, CI, tooling |
Coding Guidelines
- Run
npm run checkafter making changes to ensure type checking and code formatting pass - Run
npm run buildbefore committing to ensure compilation succeeds - Follow ESLint and Prettier configurations for consistent code style
Where to Start
- Add a new tool — implement a new handler in
packages/core/src/tools/ - Add a new Provider — register in
packages/core/src/models/provider-registry.ts - Improve the CLI UI — UI components in
packages/cli/src/ui/
See CONTRIBUTING.md for detailed guidelines.
Documentation
| Document | Description |
|---|---|
| API Reference | Core API interface documentation |
| SDK Guide | SDK integration and usage |
| Architecture Overview | System architecture design |
| Configuration Guide | Detailed configuration reference |
| Packaging Guide | CLI and VS Code extension packaging |
| Security Policy | Security vulnerability reporting |
| Changelog | Version release notes |
License
Licensed under the Apache License 2.0. See LICENSE for details.
Copyright 2026 郑州威光半导体有限公司 (Zhengzhou Weiguang Semiconductor Co., Ltd.)
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Community & Support
- Repository: https://atomgit.com/zzwgbdt/Hex4Code
- Issues: via AtomGit Issues
- Discussions: via Discussions
Built with TypeScript, Ink, and React.
Introduction
用我们的确定性,对抗世界的熵增;用我们的协作,定义未来的形状。Hex4Code 是面向工业级软件工程的AI编码助手,深度适配嵌入式、半导体、系统软件等重工业场景。原生对接 Makefile、CMake 构建体系,内置全流程研发流水线引擎,结构化解析编译与测试问题,支持多语言深度集成,覆盖CLI与VS Code全场景智能编码。
Customize your domain