shiro-neko/AGENTS.md

shiro-neko

Agentic coding CLI, built with Bun + TypeScript. The interactive UI is React rendered to the terminal with Ink; LLM access goes through the Vercel AI SDK (ai) with Anthropic, OpenAI, OpenAI-compatible, and MCP providers. Entry point and only executable is src/cli.tsx (bin shiro).

Commands

• bun install --frozen-lockfile — install deps (CI uses this; lockfile is bun.lock)
• bun run shiro — run the CLI from source (i.e. bun run src/cli.tsx)
• bun test — full test suite (bun:test, no other runner)
• bun run typecheck — tsc --noEmit; must pass before committing
• bun run build — bun build --compile to dist/shiro (single native binary)
• bun run release — cross-compile all five targets into dist/release/
• No linter or formatter is configured; don't invent one.

CI (.github/workflows/ci.yml) runs install → typecheck → test → build on Ubuntu, macOS, and Windows, pinned to Bun 1.3.14. Everything must be cross-platform: the tools shell out to the platform shell, and paths in code and tests go through node:path, never hardcoded /.

Layout

• src/ — flat modules, one concern per file, lowercase names (session.ts, prune.ts). src/ui/ holds the Ink components, PascalCase (App.tsx, Panels.tsx).
• test/ — one <name>.test.ts per src/<name>.ts; *.test.tsx for UI tests via ink-testing-library. test/helpers.ts has testHooks(), the standard App fixture.
• docs/ — user-facing docs, one per feature area.
• scripts/ — release.ts, install.ts (+ .sh/.ps1 installers).
• src/version.ts — hardcoded VERSION; the release workflow fails if it disagrees with the git tag.

Conventions

• ES modules, verbatimModuleSyntax on: import types with import type. Strict TS with noUncheckedIndexedAccess — indexing gives T | undefined, so handle it (arr[i]! appears where provably safe).
• Uses Bun APIs directly (Bun.file, Bun.write, Bun.spawn, Bun.Glob) — no fs-extra, no node shims. File tools read/write through Bun.*, not fs, where practical.
• Path safety: every user/model-supplied path goes through jail() (in src/ignore.ts), which rejects escapes outside process.cwd(). Tools resolve paths against process.cwd().
• Error handling: tool execute functions return error text to the model or throw Error with a plain message — no error classes, no codes. Storage reads (store.ts, memory.ts) catch and degrade to empty rather than throw on corrupt JSON.
• Tools are AI-SDK tool() objects with zod inputSchema. Any tool that mutates the workspace must be added to MUTATING_TOOLS in src/tools.ts — a test in permission.test.ts fails otherwise. The permission system (src/permission.ts) matches rules against the tool's subject (command for bash, path for file tools) with glob matching, and is pure/no-IO on purpose.
• Comments explain why, often naming the failure being guarded against. Match that style.
• Tests import from bun:test, build mock models with MockLanguageModelV4 + simulateReadableStream from ai/test, and each test that touches the filesystem does process.chdir() into a fresh mkdtemp dir in beforeEach and restores in afterEach.

Surprising / easy to break

• bun test runs the whole suite including fallback-live.test.ts, which spins up real local HTTP servers via Bun.serve, and commit.test.ts, which runs real git in temp repos — both need a working network stack and git on PATH.
• Tool output is capped (MAX_OUTPUT in src/tools.ts); read_file returns NUL-sniffed binary files as an error. Don't remove these — they stop a model from burning its context.
• Ink renders to the terminal, so library warnings are suppressed at the top of cli.tsx (AI_SDK_LOG_WARNINGS = false); anything written to stderr tears the UI.
• Sessions, memory, and history live under ~/.shiro-neko/, relocatable with SHIRO_HOME; tests depend on that env var to isolate state. Don't resolve the path eagerly at module load — store.ts resolves it per call for this reason.
• Release tags must match src/version.ts exactly or release.ts stops the build.