cc.nvim CLAUDE.md

cc.nvim

Pure-Lua Neovim plugin that replaces the Claude Code TUI with two buffers — an editable markdown prompt and a foldable output buffer. Spawns the claude CLI as a persistent subprocess via vim.uv.spawn() and renders its NDJSON stream-json protocol. Zero runtime dependencies beyond claude in $PATH and Neovim 0.10+.

User-facing docs live in README.md; contributor guidance in CONTRIBUTING.md. This file is for agents working in the repo.

Architecture

Sessions are backed by a provider (lua/cc/providers/) selected by config.provider: claude (default) or codex. A provider owns its subprocess, wire protocol, history listing, and approval encoding, and drives the shared renderer through provider-neutral entry points (output.lua methods, session.lua fields). Never leak provider wire messages into shared UI code; translate inside the provider.

Claude pipeline (one direction, top to bottom):

providers/claude.lua   provider interface (spawn/send/interrupt/history)
process.lua            spawn + stdio pipes (vim.uv)
parser.lua             NDJSON line buffer
router.lua             dispatch by message type
output.lua             render to buffer  ←→  session.lua  (turn/token/cost state)

Codex pipeline: providers/codex.lua spawns codex app-server, reuses parser.lua for line splitting, and does JSON-RPC correlation + thread-item → render translation itself (no router). Protocol reference: codex app-server generate-json-schema --out <dir> from the installed CLI; verified against codex-cli 0.144.5.

• plugin/cc.lua registers :Cc* commands; lua/cc/init.lua is the public module and instance manager. Multiple sessions are supported, keyed by prompt bufnr in a module-level instances table. attach_provider in init.lua is the single construction path for new/clear/resume sessions.
• lua/cc/output/ holds extracted render helpers (cost, foldtext, timers, tool_body). Most rendering work lands in output.lua plus one of these.
• NDJSON protocol reference (when extending message handling): ~/src/claude-code/src/entrypoints/sdk/coreSchemas.ts and ~/src/claude-code/src/cli/structuredIO.ts. Caveat: this local copy is a snapshot from around March 2026 and will never be updated. Treat any determination made from it as suspect and verify against the running CLI before relying on it. The further we get from that snapshot date, the more likely the source has drifted, and the more we'll have to reverse-engineer observed CLI behavior when it doesn't match what the source predicts.