Repository-level Agent Guide

Reply in the same language as the user.

This is a TypeScript monorepo built for agent-assisted development. Keep the root AGENTS.md limited to hot-path rules: the project map, hard constraints, and workflow requirements — things every task needs to know.

Working Principles

• Think from first principles. Start from real requirements, code facts, and verification results; if the goal is unclear, discuss it with the user first.
• Treat code, not documentation, as the source of truth for behavior. Implement and test functionality before catching prose up; early coding does not wait for documentation. Outside an explicit documentation task or catch-up stage, do not read ordinary Markdown just to understand the implementation. At a coherent candidate, classify the documentation impact and satisfy the applicable handoff or release boundary in docs/AGENTS.md.
• Before making code changes, read the relevant code and the most recent constraints, and follow the nearest AGENTS.md in the directory tree.
• Keep changes focused. Do not slip in unrelated refactors along the way.
• When committing, do not add any co-author attribution, and do not reveal the identity of the agent in commit messages, PR descriptions, or any explanatory text.

Project Map

• apps/kimi-code: the CLI / TUI application. It consumes @kiki/klient / @kiki/session-core for client operations and @kiki/node-sdk for host setup and SDK utilities; it must not depend directly on @kiki/agent-core-v2. When writing or modifying its terminal UI, use the write-tui skill (.agents/skills/write-tui/SKILL.md).
• apps/kiki-gui: the shared browser and desktop GUI. apps/kimi-code builds it into the CLI package and serves it from kiki web; for development, run pnpm dev:server and point the GUI Vite server at it with KIKI_SERVER_URL. Default visual acceptance uses the headless scripts/visual-proof.mjs; see apps/kiki-gui/AGENTS.md.
• packages/agent-core-v2: the agent engine — the only one. (The historical v1 packages/agent-core was deleted; nothing in the repo may reintroduce it.) A DI × Scope design with three LifecycleScope tiers (App / Session / Agent, src/app/scopes.ts), the L3 unit layer (Service/Fiber, collections, Features), and App-scope ISessionManager. Workspace resources live in leased WorkspaceInstance / Program runtime generations, not a fourth DI scope. See packages/agent-core-v2/AGENTS.md and use the agent-core-dev skill (.agents/skills/agent-core-dev/SKILL.md) when developing here.
• packages/node-sdk: the public TypeScript SDK and harness.
• packages/kaos: the execution environment and file/process abstractions.
• packages/oauth: Kimi OAuth and managed auth utilities.
• packages/transcript: the isomorphic transcript rendering data layer — L1 agent-granular store, L2 idempotent operations, L3 off/turn/block/delta subscription granularity, L4 framework-free view registry, plus turn-cursor pagination. Pure TypeScript (browser-safe, no engine imports); the sole owner of the transcript contract types (src/contract/) and the op-batch sequencing contract. See packages/transcript/AGENTS.md.
• packages/kap-server: the Kiki server, backed by @kiki/agent-core-v2; exposes sessions over REST + WebSocket (/api + /api/ws), plus the /api/debug/* reflection RPC surface (--debug-endpoints, loopback bind + bearer auth). See packages/kap-server/AGENTS.md.
• packages/klient: the client SDK — a contract-driven facade over agent-core-v2 (global.* / session(id).* / agent(id).*, zod-validated); transport via subpath entry (@kiki/klient/http|ipc|memory, all return the same Klient); also hosts the e2e suites. See packages/klient/AGENTS.md.
• packages/tree-sitter-bash: a pure-TypeScript bash parser (no runtime deps, no wasm); parse(source, { timeoutMs, maxNodes }) runs under a deterministic budget and returns a discriminated ParseResult — callers must treat aborted/hasError trees as "cannot analyze" and degrade. Parser only, no safety judgments; see the package README's "Known differences" section.
• packages/lexical: dependency-free ASCII/CJK tokenization and Unicode literal normalization shared by Memory, history, search and legacy MiniDb APIs.
• packages/minidb: the legacy embedded document store retained during the storage migration; global search uses SQLite instead. See packages/minidb/AGENTS.md.

Environment Requirements

• Node.js: >=24.22.1 <25 || >=26.12.1 (from the root package.json engines). .nvmrc is 24.22.1, the 24 LTS pin used by nvm / fnm / mise and CI. Node.js 26 is accepted from 26.12.1. Node.js 25 and Node.js 26 releases before 26.12.1 are rejected.
• pnpm: 10.33.0 (from the root package.json packageManager).
• pnpm install will fail when the Node version is not satisfied, because .npmrc sets engine-strict=true.

Monorepo Workspace Maintenance

• pnpm-workspace.yaml is the source of truth for workspace membership, but flake.nix also contains hardcoded workspacePaths and workspaceNames lists.
• Whenever you add or remove a workspace package, you MUST update both pnpm-workspace.yaml and flake.nix — for every package, including leaf / test / e2e packages that nothing depends on.
  • pnpm-workspace.yaml uses globs (packages/*, apps/*), so most packages land there automatically; flake.nix is fully manual and is where omissions happen.
  • Missing a path in flake.nix's workspacePaths will silently drop files from the Nix build's src fileset.
  • Missing a name in flake.nix's workspaceNames will break pnpmConfigHook because dependencies for that workspace will not be fetched.
• The automated "Check flake.nix workspace sync" (scripts/check-nix-workspace.mjs) verifies the full workspace in both directions: every package selected by pnpm-workspace.yaml must appear in both flake.nix lists, and stale flake entries with no workspace package fail the check. Keep it green on every add/remove, but still update both files by hand in the same change — the check only runs in CI.

Upstream Synchronization

• Never merge upstream into apps/* or packages/*; receive selected upstream changes only through isolated cherry-picks or semantic ports.
• Review upstream at every release tag or every four weeks, whichever comes first. Filter candidates by commit title and touched paths before reading full diffs.
• Review security/CVE fixes, provider protocol mismatches, and wire or persistence data-corruption fixes as soon as they appear rather than waiting for the regular review.
• Exclude UI changes, cloud features, secondary-model work, and runtime-to-DI/actor migrations in the first filter unless a separate Kiki decision explicitly reopens that area.
• Record every accepted, rejected, or deferred upstream commit in handoffs/2026-08-31-kiki-parallel-campaigns/merge-log.md using the existing date / source / local HEAD / notes table format.

General Coding Rules

• packages/agent-core-v2, packages/kap-server, and packages/transcript are comment-free zones: no line/block comments; the exceptions are JSDoc attached to exported symbols and load-bearing lint-suppression directives (oxlint-disable / eslint-disable), while other tooling directives (@ts-expect-error, …) stay banned. Enforced by scripts/check-no-comments.mjs, which runs as part of pnpm lint.
• For optional object properties, pass undefined directly instead of using conditional spread.
  • YES: { user }
  • NO: { ...(user ? { user } : undefined) }
• Optional object properties do not need to additionally allow undefined in the type.
  • YES: interface Options { user?: User }
  • NO: interface Options { user?: User | undefined }
• Internal methods with only a single parameter should not be turned into options objects just for stylistic uniformity.
• Except for a package's index.ts, other index.ts files should prefer export * from './module';.
• Do not add too many new test files. Prefer adding tests to the existing test file of the corresponding component or module.
• When a test fails because of a user modification, default to fixing the test first; do not change the implementation to satisfy an old test unless the implementation truly has a bug.
• Do not sacrifice code quality for external compatibility unless the user explicitly asks for it. Breaking changes go through changesets and a major bump, gated by the rule below.

Experimental Features

• Product features are available by default, including new features. Use an experimental flag only for a real rollout or rollback boundary; do not add another master gate to an ordinary feature that already has its own configuration. A default: false needs an explicit human requirement and its source, not a precaution about possible defects. Smoke-test and repair defects instead.
• Availability does not authorize new external connections, plugin installation, or script execution. Preserve explicit user off choices, per-destination consent, and permission rules. Flag precedence remains per-flag env > [experimental] config > truthy master env > registry default; a falsy master env is unset, not a global off command.
• Flag definitions remain distributed: declare them in the owning domain through registerFlagDefinition at import time, then use IFlagService.enabled(id) (see packages/agent-core-v2/docs/flag.md). Every built-in id also needs a Settings home, accurate application timing, and English/Chinese name and description in packages/session-core; the distributed-registration regression in src/settings/settings.test.ts must stay green. Unknown-server fallback is for extensions, not missing built-in copy.

Where to Update Instructions

• Hard rules that affect almost every task: update the root AGENTS.md.
• Rules that only affect a specific directory: update the nearest sub-directory AGENTS.md.
• Project-map entries stay at 1–2 sentences; deep package docs live in the package's own AGENTS.md.
• Keep instruction updates focused and supported by code facts.

Workflow Requirements

• Prefer rg / rg --files when reading code.
• When designing changes, follow existing boundaries and local patterns first.
• In public text and test data, replace real internal identifiers with neutral placeholders such as example.com, example.test, and YOUR_API_KEY. Before opening a PR, ask a read-only agent to audit the diff for context-specific internal identifiers.
• When creating a PR, the PR title must follow Conventional Commit style, e.g. chore: remove legacy format commands.
• When an AI agent opens or updates a PR, fill in .github/pull_request_template.md — link the related issue or explain the problem, then describe what changed. Do not leave placeholder text or submit a generic summary of the diff.
• Do not submit vague AI-generated PR text. The human author must understand the change well enough to explain the code, edge cases, and why the approach fits this repository.
• After finishing a task and before submitting a PR, you must run the gen-changesets skill (see .agents/skills/gen-changesets/SKILL.md) and generate a changeset under .changeset/ according to its rules.
• Changesets must strictly follow the rules in .agents/skills/gen-changesets/SKILL.md: write one short user-facing sentence that states only what changed, and skip any change users cannot perceive.
• When generating a changeset, never decide on a major bump on your own — stop, explain, and get explicit user confirmation first; default to minor, fall back to patch. See .agents/skills/gen-changesets/SKILL.md.
• Prefer importing via import ... from '#/...', which serves the same purpose as import ... from '@/...'.
• Do not commit throwaway scratch or exploratory files. Never stage:
  • Agent working notes or handoff/summary documents (e.g. HANDOVER-*.md, HANDOFF-*.md, handoff.md).
  • Throwaway UI/UX prototypes or design mockups (e.g. *-designs.html, *-mockup.html, *-demo(s).html) at the repo root or under a design/ folder. The only tracked .html files should be Vite index.html entrypoints. Before committing or opening a PR, run git status and git diff --staged --stat and remove anything matching these patterns. Put scratch work under .tmp/ (gitignored) instead of the repo root or the source tree.