There is agents which @CLAUDE.md should refer to...

545a7c76.md

session-id	545a7c76-6d44-4959-bf87-e1cab823a816

User

/arthack:claudify

Skill loaded: arthack:claudify

Assistant

Thought (1 line)

Starting claudify. Let me orient first.

Glob **/CLAUDE.md (0 files)

Bash git rev-parse --show-toplevel (1 line)

Mode: Bootstrap — zero CLAUDE.md files found. Repo root is /Users/mike/src/rockorager--prise.

Now let me map the repo shape.

Bash ls -1 /Users/mike/src/rockorager--prise/ (16 lines)

Glob **/package.json (0 files)

Glob **/pyproject.toml (0 files)

Glob **/Cargo.toml (0 files)

Glob **/go.mod (0 files)

Glob **/Makefile (0 files)

Glob **/CMakeLists.txt (0 files)

Glob **/README.md (1 file)

Glob **/.github/workflows/*.yml (4 files)

Bash git -C /Users/mike/src/rockorager--prise log --oneline -20 (20 lines)

Thought (1 line)

Zig project with Nix packaging. Let me get a bit more structure detail.

Bash ls -1 /Users/mike/src/roc...--" && ls -1 /Users/mike/src/rockorager--prise/dist/ (37 lines)

Good. Now I have the shape. Let me identify which directories need CLAUDE.md files:

• / (root) — cross-cutting: Zig build, Nix, CI, project overview
• src/ — main source with sub-modules (io/, lua/), probably the core of the project
• tools/ — has mdman, possibly build/doc tooling

Let me check if src/io/ and src/lua/ are substantial enough to warrant their own files.

Bash ls -1 /Users/mike/src/roc... && ls -1 /Users/mike/src/rockorager--prise/src/lua/ (11 lines)

Thought (17 lines)

The repo is a Zig terminal multiplexer with:

• src/ — core Zig source with io/ (kqueue/io_uring backends) and lua/ (Lua scripting/config)
• tools/mdman — documentation tooling
• docs/ — man pages and web content
• dist/ — systemd service
• Nix packaging (flake.nix, shell.nix)
• GitHub CI/CD workflows

Directories that need CLAUDE.md files:

1. / (root) — cross-cutting: build, test, CI, architecture overview
2. src/ — has enough internal structure (io backends, lua subsystem, UI, keybinds) to warrant local context

tools/, docs/, dist/ are small and straightforward — root CLAUDE.md can cover them.

Now spawning parallel research agents.

Agent Research src directory (245 lines)

Agent Research root directory (452 lines)

Thought (24 lines)

Research complete. Here's the plan.

---

Proposed CLAUDE.md Files

Directory	Purpose	Lines
/	Build, test, project structure, key references	~55
src/	Architecture, module map, patterns	~65

---

Proposed: /CLAUDE.md

### Prise

Modern terminal multiplexer written in Zig with Lua scripting. Alpha software (v0.3.1).

#### Build & Run

| Command                                      | Purpose                                         |
| -------------------------------------------- | ----------------------------------------------- |
| `zig build`                                  | Compile                                         |
| `zig build run`                              | Compile and run                                 |
| `zig build test`                             | Run all tests + format checks + Lua type checks |
| `zig build fmt`                              | Format Zig and Lua code                         |
| `zig build setup`                            | Install pre-commit hook                         |
| `zig build man`                              | Generate man pages                              |
| `zig build web`                              | Generate HTML docs                              |
| `zig build install --prefix ~/.local`        | Install binary and support files                |
| `zig build enable-service --prefix ~/.local` | Install and start background service            |

Build options: `-Doptimize=ReleaseSafe`, `-Dlua-check=false` (skip Lua type checking), `-Dtarget=x86_64-linux` (cross-compile).

Minimum Zig version: 0.15.2. Use `nix develop` for a reproducible dev shell with all tools.

#### Testing

`zig build test` runs everything: Zig unit tests, `zig fmt --check`, `stylua --check`, and lua-language-server type checking. All must pass in CI.

#### Project Structure

- `src/` — Zig source code (client-server architecture, UI, keybinds, Lua integration)
- `src/io/` — Platform-specific async I/O backends (kqueue, io_uring, mock)
- `src/lua/` — Lua config/scripting library with EmmyLua type annotations
- `docs/` — Man page sources (`prise.{1,5,7}.md`), release notes, web docs
- `tools/mdman/` — Markdown-to-man-page converter
- `completions/` — Shell completions (Fish, Bash, Zsh)
- `dist/` — Systemd service template
- `assets/` — Screenshots

#### Dependencies (build.zig.zon)

- **ghostty-vt** — VT terminal sequence parsing (from Ghostty)
- **vaxis** — Terminal UI rendering
- **zlua** — Zig bindings for Lua 5.4
- **zeit** — Time/date utilities

#### Coding Conventions

See `AGENTS.md` for full coding standards. Key points:

- **Zig**: `camelCase` functions, `snake_case` variables, `PascalCase` types, `SCREAMING_SNAKE_CASE` constants
- **Lua**: `snake_case` everywhere, EmmyLua type annotations required, StyLua formatting
- **70-line function limit** — extract helpers when functions grow
- **Assertions at boundaries** — define limits as named constants, assert before operations
- **Commit messages**: imperative mood, 60-char title limit, explain what and why

#### Formatting

- Zig: `zig fmt` (runs via `zig build fmt`)
- Lua: StyLua with config in `src/lua/.stylua.toml` (4-space indent, 120 col, double quotes)

#### CI

Matrix: Ubuntu + macOS. Runs build, test (includes format + type checks). Releases triggered by `v*` tags with binaries for aarch64-macos and x86_64-linux.

#### Service

Server runs as a daemon via Unix socket at `/tmp/prise-{uid}.sock`. Managed by launchd (macOS) or systemd (Linux).

---

Proposed: src/CLAUDE.md

### src/

Client-server terminal multiplexer core. Server manages PTYs and routes messages; clients connect via Unix socket, render UI, and handle input.

#### Architecture

- **Server** (`server.zig`): Long-running daemon. Main event loop + one PTY thread per session. Non-blocking pipes signal dirty state from PTY threads.
- **Client** (`client.zig`): Short-lived process. Main event loop + TTY input thread. Renders via Vaxis with double-buffered surfaces.
- **Entry point** (`main.zig`): Dual-role binary — subcommands `serve`, `session`, `pty`. Logs to `~/.cache/prise/{client|server}.log` (64MB limit).
- **Protocol**: MessagePack-RPC over Unix socket. Format: `[type, msgid, method/error, params/result]`.

#### Module Map

**I/O & Networking:**
- `io.zig` — Platform abstraction facade (compile-time backend selection)
- `io/kqueue.zig` — macOS/BSD async I/O via kqueue
- `io/io_uring.zig` — Linux async I/O via io_uring
- `io/mock.zig` — Deterministic mock for testing

**PTY & Terminal:**
- `pty.zig` — PTY creation, process management (master/slave/pid)
- `vt_handler.zig` — Wraps ghostty-vt Terminal for escape sequence handling
- `vaxis_helper.zig` — Bridge between Vaxis key events and W3C key/code strings

**Keybind System:**
- `key_string.zig` — Parses vim-style key strings (`<C-a>`, `<D-k>v`, `<S-Tab>`)
- `keybind_compiler.zig` — Builds trie from keybind definitions, validates conflicts
- `keybind_matcher.zig` — Runtime key matching with pending state
- `keybind.zig` — Lua bindings for the keybind system
- `key_parse.zig` — Parses MessagePack key/mouse events
- `key_encode.zig` — Encodes keys for terminal protocols

**UI & Rendering:**
- `Surface.zig` — Double-buffered screen state (front/back buffers)
- `ui.zig` — Lua interpreter host, layout engine, timer management
- `widget.zig` — Widget tree with constraints, hit regions, split handles
- `TextInput.zig` — Text input widget with cursor/scroll
- `redraw.zig` — UI event types (resize, write, cursor_pos, style, selection)

**RPC:**
- `msgpack.zig` — Full MessagePack encoder/decoder with Value union type
- `rpc.zig` — MessagePack-RPC protocol layer (Request/Response/Notification)

**Actions & Events:**
- `action.zig` — Built-in action enum (split_horizontal, focus_left, quit, etc.) + lua_function variant
- `lua_event.zig` — Event types for Lua callbacks (vaxis, mouse, pty_attach, etc.)
- `mouse_encode.zig` — Mouse event encoding for PTY protocols

#### I/O Backend Pattern

Platform selected at compile time:
```zig
const backend = switch (builtin.os.tag) {
    .linux => @import("io/io_uring.zig"),
    .macos => @import("io/kqueue.zig"),
};

All backends expose: socket(), connect(), accept(), read(), recv(), send(), close(), timer(), waitpid(). Each returns a Task with cancellation support.

Lua Subsystem (lua/)

• prise.lua — Main API module
• tiling.lua — Tiling window manager UI
• utils.lua — Utility functions
• types/ — EmmyLua type definitions for IDE support
• *_test.lua — Tests run via lua_test.zig through ziglua
• .luarc.json — Strict lua-language-server config
• .stylua.toml — StyLua formatter config

Widget system: Lua view() returns a widget tree → Zig renders and collects hit regions → events route to Lua update().

File Naming

• PascalCase.zig: Primary type files (Surface.zig, TextInput.zig)
• snake_case.zig: Modules and utilities (key_parse.zig, vt_handler.zig)
• *_test.zig/*_test.lua: Test files

Testing

• Zig: Inline test blocks in source files. All test modules registered in main.zig.
• io/mock.zig provides deterministic async testing: completeConnect(), completeRecv(), etc.
• tui_test.zig has screenToAscii() for visual UI assertions.
• Lua: *_test.lua files executed through lua_test.zig via ziglua.

Server Limits

Defined in server.zig as LIMITS: 64 clients, 256 PTYs, 16MB messages, 1024 send queue. Always check and respect these constants.

---

How would you like to proceed?

1. **Approve all** — write both files
2. **Cherry-pick** — include/exclude specific files
3. **Request changes** — modify proposals
4. **Abort** — write nothing

*Permission mode: default*

## User

There is agents which @CLAUDE.md should refer to and let's remove anything redundant from @flake.lock

*Request interrupted by user*

## User

There is agents which CLAUDE.md should refer to and let's remove anything redundant from CLAUDE.md

## Assistant

*Thought (5 lines)*

Let me check what AGENTS.md already covers so I can trim the duplication.

> **Read** `~/src/rockorager--prise/AGENTS.md` *(141 lines)*

*Thought (23 lines)*

Good — AGENTS.md already covers coding style, naming, build/test/fmt commands, testing patterns (including mock event loop), pre-commit checks, and commit message format. I'll strip all of that from CLAUDE.md. Here are the revised proposals:

---

##### Proposed: `/CLAUDE.md` (~25 lines)

```markdown
### Prise

Modern terminal multiplexer written in Zig with Lua scripting. See `AGENTS.md` for coding conventions, build commands, testing, and commit format.

#### Project Structure

- `src/` — Zig source (client-server architecture, UI, keybinds, Lua integration)
- `src/io/` — Platform-specific async I/O backends (kqueue, io_uring, mock)
- `src/lua/` — Lua config/scripting library with EmmyLua type annotations
- `docs/` — Man page sources (`prise.{1,5,7}.md`), release notes, web docs
- `tools/mdman/` — Markdown-to-man-page converter
- `completions/` — Shell completions (Fish, Bash, Zsh)
- `dist/` — Systemd service template

#### Additional Build Commands

| Command                                      | Purpose                              |
| -------------------------------------------- | ------------------------------------ |
| `zig build setup`                            | Install pre-commit hook              |
| `zig build man`                              | Generate man pages                   |
| `zig build web`                              | Generate HTML docs                   |
| `zig build install --prefix ~/.local`        | Install binary and support files     |
| `zig build enable-service --prefix ~/.local` | Install and start background service |

Build options: `-Doptimize=ReleaseSafe`, `-Dlua-check=false` (skip Lua type checking), `-Dtarget=x86_64-linux` (cross-compile).

#### Dependencies (build.zig.zon)

- **ghostty-vt** — VT terminal sequence parsing (from Ghostty)
- **vaxis** — Terminal UI rendering
- **zlua** — Zig bindings for Lua 5.4
- **zeit** — Time/date utilities

Minimum Zig version: 0.15.2. Use `nix develop` for a reproducible dev shell.

---

Proposed: src/CLAUDE.md (~50 lines)

### src/

Client-server terminal multiplexer core. See root `AGENTS.md` for coding conventions and testing patterns.

#### Architecture

- **Server** (`server.zig`): Long-running daemon. Main event loop + one PTY thread per session. Unix socket at `/tmp/prise-{uid}.sock`.
- **Client** (`client.zig`): Short-lived process. Main event loop + TTY input thread. Renders via Vaxis with double-buffered surfaces.
- **Entry point** (`main.zig`): Dual-role binary — subcommands `serve`, `session`, `pty`. Logs to `~/.cache/prise/{client|server}.log`.
- **Protocol**: MessagePack-RPC over Unix socket. Format: `[type, msgid, method/error, params/result]`.

#### Module Map

**I/O:** `io.zig` facade with compile-time backend selection → `io/kqueue.zig` (macOS), `io/io_uring.zig` (Linux), `io/mock.zig` (tests). All backends expose `socket()`, `connect()`, `accept()`, `read()`, `recv()`, `send()`, `close()`, `timer()`, `waitpid()`.

**PTY & Terminal:** `pty.zig` (PTY creation/process management), `vt_handler.zig` (ghostty-vt wrapper), `vaxis_helper.zig` (Vaxis↔W3C key bridge).

**Keybind System:** `key_string.zig` (vim-style key parsing: `<C-a>`, `<D-k>v`) → `keybind_compiler.zig` (trie builder) → `keybind_matcher.zig` (runtime matching) → `keybind.zig` (Lua bindings). Also `key_parse.zig` / `key_encode.zig` for wire format.

**UI:** `Surface.zig` (double-buffered screen), `ui.zig` (Lua host + layout engine), `widget.zig` (widget tree + constraints), `TextInput.zig`, `redraw.zig` (event types).

**RPC:** `msgpack.zig` (encoder/decoder with Value union), `rpc.zig` (protocol layer).

**Actions & Events:** `action.zig` (built-in action enum + lua_function variant), `lua_event.zig` (Lua callback events), `mouse_encode.zig`.

#### Lua Subsystem (`lua/`)

- `prise.lua` — Main API. `tiling.lua` — Tiling WM. `utils.lua` — Helpers.
- `types/` — EmmyLua type definitions for IDE support.
- Widget flow: Lua `view()` → widget tree → Zig renders + collects hit regions → events route to Lua `update()`.

#### File Naming

- **PascalCase.zig**: Primary type files (`Surface.zig`, `TextInput.zig`)
- **snake_case.zig**: Modules and utilities (`key_parse.zig`, `vt_handler.zig`)

#### Server Limits

Defined as `LIMITS` in `server.zig`: 64 clients, 256 PTYs, 16MB messages, 1024 send queue.

---

How would you like to proceed?

1. Approve all — write both files
2. Cherry-pick — include/exclude specific files
3. Request changes — modify proposals
4. Abort — write nothing