tinycode: Instructions file for Codex

Shared project rules for coding agents. Keep this file in sync with CLAUDE.md. CLAUDE.md also has a Claude-only agent delegation section.

Commands

# Build
make build                      # builds dist/tinycode

# Run
./dist/tinycode                 # TUI mode
./dist/tinycode <directory>     # TUI against a different directory
./dist/tinycode serve           # headless API proxy
./dist/tinycode acp             # Agent Client Protocol (IDE integration, stdio)

# Tests
go test ./... -count=1          # all tests (or: make test)
go test ./internal/tui/... -count=1   # single package

# Lint
make lint                       # go vet + staticcheck (make test-race for -race)

# Embed web app into binary (requires packages/app built first)
make embed-webapp

Commits and PR Titles

Use conventional commit-style messages and PR titles: type(scope): summary.

Valid types are feat, fix, docs, chore, refactor, and test. Scopes: tui, server, llm, session, provider, config, tool, plugin, acp, permission, mcp, vcs, bus, storage, agent, skill, command, project.

Style Guide

• Follow standard Go conventions (gofmt, go vet)
• Prefer early returns over else blocks
• Keep functions focused and small; extract helpers when they name a real concept
• Use slog for structured logging (already used throughout)
• Error handling: return errors up the stack with fmt.Errorf("context: %w", err). Don't swallow errors silently.
• Prefer value receivers for bubbletea Update/View methods (required by the tea.Model interface)
• Use pointer receivers for methods that mutate state (e.g. resize(), setFocus())
• Test files live next to source: foo.go / foo_test.go

Testing

• Use table-driven tests where appropriate
• Test names: TestFunctionName_ScenarioDescription
• Run from repo root: go test ./... or target a package: go test ./internal/tui/...

Pitfalls

Things that break silently if you guess wrong.