44 lines
2.6 KiB
Markdown
44 lines
2.6 KiB
Markdown
# TUI Documentation for Claw Code
|
|
|
|
This directory contains all research, analysis, and architecture documentation for the TUI mode (`claw tui`).
|
|
|
|
## Architecture Plan
|
|
|
|
- **[ARCHITECTURE.md](./ARCHITECTURE.md)** — The definitive architecture plan, synthesized from 5 expert MoA (Mixture of Agents) reports. This is the implementation blueprint.
|
|
|
|
## Original Plans
|
|
|
|
- **[TUI.md](./TUI.md)** — Initial research & build plan
|
|
- **[TUI-52-WEEK-PLAN.md](./TUI-52-WEEK-PLAN.md)** — 52-week roadmap
|
|
- **[TUI-52-WEEK-SPRINT.md](./TUI-52-WEEK-SPRINT.md)** — Sprint-level breakdown
|
|
|
|
## MoA Research Reports
|
|
|
|
Five independent expert analyses were conducted before writing the architecture plan:
|
|
|
|
| Report | Focus | Key Takeaway |
|
|
|--------|-------|--------------|
|
|
| [moa-codex-rs.md](./moa-codex-rs.md) | OpenAI's codex-rs/tui — closest prior art | `tokio::select!` event loop, demand-driven frames, active/committed cell split, adaptive 2-gear chunking |
|
|
| [moa-aichat.md](./moa-aichat.md) | sigoden/aichat streaming markdown rendering | "Erase-and-redraw" with 50ms batch, LineType state machine, textwrap for CJK |
|
|
| [moa-ecosystem.md](./moa-ecosystem.md) | Broader Rust TUI ecosystem survey | **Render to stderr** to solve output bleeding; tui-markdown, ansi-to-tui, virtual scroll, testing patterns |
|
|
| [moa-failure-analysis.md](./moa-failure-analysis.md) | Root-cause analysis of 3 failed TUI attempts | All failures share one root: runtime prints to stdout; TUI grafted on top |
|
|
| [moa-runtime-integration.md](./moa-runtime-integration.md) | claw-code runtime integration points | `TurnProgressReporter` only fires post-tool; `ApiClient::stream()` returns collected Vec — no live streaming channel |
|
|
|
|
## Reading Order
|
|
|
|
1. **ARCHITECTURE.md** — The plan (start here)
|
|
2. **moa-failure-analysis.md** — Why the previous 3 attempts failed
|
|
3. **moa-codex-rs.md** — The closest working reference implementation
|
|
4. **moa-ecosystem.md** — Broader patterns and crate recommendations
|
|
5. **moa-aichat.md** — Streaming markdown rendering deep-dive
|
|
6. **moa-runtime-integration.md** — How to hook into claw-code's runtime
|
|
|
|
## Key Decisions
|
|
|
|
- **Render to stderr** — stdout freed for child processes, eliminates output bleeding
|
|
- **Event-driven architecture** — runtime emits `TuiTurnEvent` via channel, TUI consumes
|
|
- **Forward-offset scroll** — 0=top, max=bottom (kills the inverted-scroll bugs)
|
|
- **Active cell + committed cells** — streaming cell flushed to markdown cell on completion
|
|
- **Modify `ApiClient::stream()`** — return async stream for live token rendering
|
|
- **`--tui-stdio` mode** — JSON-over-stdio for programmatic driving (separate PR)
|