hexa-lang 으로 처음부터 plugin-first 로 짠 AI 코딩 에이전트. hive(pi-mono fork 가 너무 baked-in 돼서 25k 파일 + 3중 dual 마이그레이션으로 못 끝남)의 후계 개념 — 미니멀 core + 전부 플러그인.
상태: 설계 + pre-implementation 초안 단계 (2026-05-10).
core/*.hexa+plugins/*/는 스켈레톤 초안 (시그니처 + 계약 주석 + STUB 바디). 컴파일 검증은 빌드 호스트에서. 아직 실행 가능한 바이너리 없음.🤖 AI 에이전트는 먼저
AGENTS.md를 읽으세요 — 빌드 갭 현황, 컨벤션, 함정, 세션 프로토콜. (agents.md 표준;CLAUDE.md는 같은 파일에 심볼릭 링크.)🪪 wilson 의 컨텍스트 파일 =
AGENTS.md(Claude Code 의CLAUDE.md/ Gemini 의GEMINI.md등가물). wilson 은 임의 프로젝트에서 띄우면 그 프로젝트의AGENTS.md를 walk-up 으로 발견해 시스템 프롬프트 앞에 자동 prepend — 단일 SSOT 원칙이라 wilson 은CLAUDE.md/GEMINI.md/.cursorrules를 따로 안 읽음 (사용자가 그 파일들을AGENTS.md로 심볼릭 링크하면 모든 도구가 같은 SSOT 봄). 구현:plugins/agents-md/, 디폴트 번들 멤버, opt-outWILSON_NO_AGENTS_MD.
┌─ wilson (멀티-콜 정적 hexa 바이너리, busybox 식) ───────────────────────┐
│ │
│ core/ = 어휘 + 골격 + the wire + 로더 + provider 인터페이스 + TUI │
│ types.hexa host.hexa event_bus.hexa loader.hexa │
│ agent_loop.hexa main.hexa test_fixture.hexa │
│ core 는 어떤 plugin 이 무슨 행동을 하는지 모름 — 로드하고 이벤트를 펌프할 뿐 │
│ │
│ + static-linked 디폴트 번들 plugin (plugins/_bundle): │
│ harness-cli · harness-print · harness-rpc · tool-core · provider-anthropic │
└──────────────────────────────────────────────────────────────────────────┘
별 프로세스 (무거운/위험/세션-무관): wilson plugin-daemon <id> <comp>
swarm cell: wilson --harness rpc (= 같은 바이너리, 다른 모드)
external-repo dep (큰 덩어리): bedrock(governance) · resource(host pool)
- core = irreducible — 메시지 타입(
Message/ToolCall/AsmEventpayload-enum/HookEvent) + 에이전트 루프 골격 + 이벤트 버스(fire_hook: validate 단락 → transform fold → observe) + plugin 로더(@pluginmanifest 파싱 + 9-step 검증 + dispatch 라우팅) + provider 인터페이스(handle-basedstream_open/next/close) + TUI 프리미티브. 그게 전부. - everything else = plugin —
pub fn <id>_dispatch(action, payload) -> any하나 +@plugin(...)manifest. providers / tools / hooks / commands / views / governance / memory / compaction / resource-mgmt / swarm / bridges — 전부. 핫패스 plugin =wilson정적 바이너리에 static link, 무거운/위험/세션-무관 = 별 프로세스 + JSONL IPC, 큰 governance/resource 덩어리 = external repo (bedrock/resource) 를 plugin dep 으로. - TS 0 — 전부 hexa-lang. dual-twin 안 함.
.hexa는 hexa-langRULES.md준수(>=/<=금지,exec()정책 주석, no silent catch/exit) + PORT_PITFALLS 함정 회피.
project.hexa wilson hexa project SSOT (@project + 컨벤션 + non-goals)
README.md this file
wilson.webp header image
core/ irreducible core — README.md + 7 .hexa skeleton drafts
plugins/ everything-not-core
_bundle/ meta-package — 디폴트 번들 멤버 목록 (wilson build 가 읽음)
_bundle_cell/ swarm-cell minimal 번들 (harness-rpc + tool-core + provider)
harness-cli/ TTY REPL harness (input loop 점유, /help·/clear·/exit)
harness-print/ -p print mode (한 턴 → stdout → exit)
harness-rpc/ --harness rpc — JSONL stdin/stdout (swarm cell 본체)
tool-core/ read·write·edit·bash·glob·grep tools
provider-claude-cli/ Claude CLI provider (`claude -p`, OAuth) — 디폴트 provider
provider-anthropic/ Anthropic Messages API SSE 스트리밍 provider (API key fallback)
agents-md/ 세션 시작시 AGENTS.md walk-up + system_prompt prepend
bridge-hexa/ `hexa` CLI 를 구조화된 tool 로 (parse/build/cc/run)
bridge-git/ `git` CLI 를 구조화된 tool 로 (status/diff/log/branch/commit/...)
bridge-gh/ `gh` CLI 를 구조화된 tool 로 (pr/issue/release/repo/run/api/...)
hello/ trivial 예시 plugin (writing-plugins.md 의 레퍼런스)
governance/ memory/ compaction-local/ compaction-llm/ (opt-in hook plugins)
resource-management/ statusline/ swarm/ (opt-in)
<id>/{plugin.hexa, main.hexa, test_<id>.hexa} (per-plugin layout)
docs/ design docs (아래)
2-축 분류 — family (4 + misc) × category (10). SSOT 는 core/loader.hexa
(plugin_family / plugin_category); wilson plugin list 가 grouped 로 렌더링.
풀 테이블 + 멤버는 plugins/README.md 참조.
| family | 뜻 | categories | 멤버 |
|---|---|---|---|
| io | 들어오고 나가고 | harness · provider · bridge |
harness-{cli,print,rpc} · provider-{claude-cli,anthropic} · bridge-{hexa,git,gh} |
| tools | 무얼 하고 | tool |
tool-core |
| policy | 어떻게 감싸고 | context · guardrail · telemetry |
agents-md · memory · compaction-{local,llm} · governance · resource-management · permission-gate · statusline · progress · recap |
| orchestration | 여럿이 함께 | orchestration |
swarm |
| misc | 그 외 | example · meta |
hello · _bundle · _bundle_cell |
Bridge = 외부 CLI / 시스템을 구조화된 tool 로 감싸는 어댑터 (graceful absence — 피어 CLI 부재시
ok=true, is_error=false). 코딩 에이전트가 자주 쓰는 도구는 디폴트 번들에 포함 (bridge-{hexa,git,gh},
~200 LoC 씩, opt-out WILSON_NO_BRIDGE_{HEXA,GIT,GH}=1).
| doc | 내용 |
|---|---|
docs/ROADMAP.md |
plan SSOT — phased build plan (P0 hexa-lang 게이트 → P1 core skeleton → P2 minimal 번들 → P3 governance+memory+compaction → P4 resource-management → P5 swarm+bridges → P6+) + 열린 결정 |
docs/plugin-architecture-brainstorm.md |
core/plugin 경계, 2축 분류, host contract, manifest+lifecycle, resource-mgmt·governance deep dive, "harness as plugin", 안티패턴 |
docs/plugin-interfaces-comms-aot-brainstorm.md |
Part A 구체 인터페이스 (<id>_dispatch, provider handle-based, tool/hook/command/view/harness 시그니처) · Part B 통신 ({op,args}→{ok,result,error} envelope, 5채널) · Part C 컴파일-hexa 링크/배포 (static-link-all / 분리바이너리+IPC / compile-on-demand; dlopen=미래) |
docs/plugin-manifest-schema.md |
@plugin(...) 풀 필드 스키마 + dispatch 계약 + 9-step load 검증 |
docs/wilson-cli-argv-modes.md |
busybox 멀티-콜 CLI — interactive / -p / --harness rpc / 서브커맨드 (doctor·build·self-update·plugin·plugin-exec·plugin-daemon·bench·reload) + env + RPC JSONL proto + exit code |
docs/writing-plugins.md |
plugin 작성 가이드 — 스캐폴드 hello 예시, 8 kind 레시피, 컨벤션, 안티패턴, 테스트, 빌드/설치 |
docs/hexa-lang-gap-audit.md |
wilson 이 의존하는 hexa-lang 갭 (G1 payload enum ✅ / G2 async model ✅(소스, binary promotion 대기) / G3 cancel token ✅ / G4 jsonschema / G5 fs atomic-append / G6 jsonl_pool / G7 dlopen / G8 incremental link) |
# 1. Install hexa-lang (gives you `hexa` + `hx` package manager)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/dancinlab/hexa-lang/main/install.sh)"
# 2. Install wilson
hx install wilsonwilson # interactive TUI (== `ws`)
wilson "first message" # interactive, seeded
wilson -p "..." # print one turn, exit
wilson --harness rpc # JSONL RPC (swarm cell)
wilson --model <id> ... # override host_config("model") for this run (any subcommand)결정적인 도구 (file IO / git / web / 빌드 / 이미지 메타 / 작업 관리 …) 는 LLM 토큰을
지불할 이유가 없다. wilson <subcommand> 는 LLM 을 거치지 않고 동일한 plugin dispatch
경로를 직접 타기 때문에 인자 / ToolResult 가 에이전트 루프와 byte-identical 이다.
스크립트, CI, 셸 파이프, 다른 에이전트의 child-tool 로 그대로 끼워 쓸 수 있다.
wilson tool <name> [--key VALUE]... [--json '{...}'] # 등록된 어떤 도구든 직접 호출
wilson tool --list # 등록된 도구 이름 전체
wilson tool read --path /etc/hosts # = tool-core read
wilson tool web_fetch --url https://anthropic.com # = tool-web web_fetch
wilson tool git --subcmd log --args -3 --args --oneline # bridge-git
wilson tool image_info --path screenshot.png # tool-image v0
wilson task <add|list|done|in_progress|delete|clear> # 영구 task 리스트 (~/.wilson/tool-task/tasks.jsonl)
wilson memory <list|add [<tier>] <text>|forget <slug>> # 4-tier 메모리 (~/.wilson/memory/*.jsonl)
wilson recap [show [<sid>] | list] # 이전 세션 핸드오프 캡슐
wilson session <list | resume <sid> | rm <sid>> # 세션 transcript 관리이 원칙은 wilson 의 디자인 기둥 — 자세한 동작 / 인자 규칙은 wilson --help 참조.
ws is the short alias for wilson — same launcher (bin/ws is a symlink to bin/wilson), same default settings, a real command on PATH (not a shell alias). hx install only wires up bin/wilson; to also get ws, one of:
ln -sf wilson ~/.hx/bin/ws # symlink ws → wilson (simplest)
# or: hx install /path/to/wilson --as ws --entry bin/ws # a second hx entry named `ws`The launcher runs the compiled build/wilson if present and runnable on this host, else hexa run core/main.hexa (the interpreter — slower start). build/wilson is produced by hexa build core/main.hexa -o build/wilson (see Build / verify).
wilson build [--with a,b] [--without c] 가 core/main.hexa + 디폴트 번들 (plugins/_bundle/plugin.hexa) ± --with/--without 를 hexa cc + hexa_ld 로 static link → wilson 정적 바이너리. dev = WILSON_DEV=1. (현 단계는 빌드 호스트에서 hexa cc/hexa build 로 컴파일 검증 — docs/ROADMAP.md 열린-결정 #5 참조.)
TBD.