kimchi AGENTS.md

Agent guidelines for Kimchi

You are editing the kimchi coding harness. This repo extends the pi-mono SDK (@earendil-works/pi-coding-agent) — core agent loop lives upstream; this repo adds extensions in src/extensions/.

Environment

• Package manager: pnpm (NEVER use npm/yarn)
• Runtime: Bun for dev (pnpm run dev), Node 22+ for built binaries
• Test runner: vitest (pnpm run test — unit, pnpm run test:smoke, pnpm run test:e2e:tui, pnpm run test:e2e:acp — e2e)
• Linter: biome (pnpm run lint, pnpm run lint:fix)
• Type check: TypeScript (pnpm run typecheck)

Hard constraints

• NEVER modify patches/ files directly — patches apply at install; changes here don't affect runtime
• NEVER touch src/core/export-html/ HTML templates — bundled JS is auto-generated from source
• Test files: Co-locate as *.test.ts alongside source (NOT in a separate test/ folder)

Development patterns

• Auto-formatting: lint:fix runs automatically after file edits (PostToolUse hook) — don't run manually
• Pre-commit: .husky/pre-commit runs pnpm run lint — CI runs full check (lint + typecheck)
• README changes: Run ./scripts/copy-resources.js --dev after editing to propagate to dist/

CLI arguments

• Declare Kimchi-local flags in src/cli-args.ts: add them to CLI_OPTIONS with type, description, and an optional short alias / placeholder. This catalog is the single source of truth for both the parser and help text.
• Read parsed CLI args via getParsedCliArgs(): do not scan process.argv by hand outside of src/cli.ts startup/bootstrap code, and do not stash CLI state on process globals. The cached parse is populated once (by cli.ts) after @file / resume-id normalization so downstream code sees the same argument list that upstream pi-mono receives.

Testing expectations

• Always add or update tests with behavior changes. Bug fixes should include a regression test that fails before the fix; new features should cover the user-visible behavior they introduce. If a test is not practical, say why in the PR/commit notes.
• Keep unit/integration tests close to the code as *.test.ts beside the source file. Prefer focused tests that exercise the contract of the module or extension being changed.
• Use TUI E2E tests for user workflows. Put terminal-level scenarios under tests/e2e/tui/*.test.ts and run them with pnpm run test:e2e:tui.
• Treat TUI E2E tests as human-designed behavioural specs. They should describe important UX flows a user would recognize, not broad agent-generated coverage. Keep one clear workflow per test, name it by the behavior, and assert on user-visible terminal text/state.
• Structure TUI tests through the shared fixture. Use runKimchiSession, deterministic fake OpenAI responses, isolated temp HOME/workdir, and trace steps for meaningful checkpoints. Avoid brittle ANSI/snapshot assertions unless the rendering itself is the behavior under test.
• Known product bugs can use test.fail. Add a short comment naming the bug/repro. When the underlying issue is fixed, the unexpected pass is the signal to remove test.fail.
• Quarantine only for unstable tests. Use tests/e2e/tui/skip-list.js with a specific reason and remove the entry as soon as the instability is fixed.
• Don't hand-write common dependency mocks in tests. Avoid creating ExtensionContext (ctx) or ExtensionAPI (pi) mocks inline inside a test file. Use shared mocks (e.g. under src/extensions/__mocks__/** for unit tests) when they exist, and add new ones there if several tests need the same dependency. Don't copy-paste partial mocks across tests.