ZacharyZhang-NY
d6c20fc13f
Hard fork of xai-org/grok-build (Apache-2.0) re-targeted as Kigi, an
unofficial Kimi Code CLI community build.
Rename & identity
- 72 xai-*/xai-grok-* crates -> kigi-* (explicit: xai-grok-pager-bin ->
kigi-bin [binary `kigi`], xai-grok-pager -> kigi-tui; rest mechanical);
ptyctl, ptyctl-cli, third_party/ unchanged; proto package
xai.grok.tools.v1 -> kigi.tools.v1
- Config home ~/.kigi (KIGI_SHARE_DIR override), env prefix GROK_* ->
KIGI_*, `kigi --version` carries the unofficial-community-build notice
- clap identity, help text, startup banner, prompt templates rebranded
(templates re-encrypted)
Deletions (PRD removal list #5/#6/#7/#9/#10)
- voice input (xai-grok-voice) and all TUI wiring
- telemetry: Mixpanel client, external OTel stream, Sentry, OTLP layers,
trace/GCS/S3 upload queues (kigi-file-utils halved), workspace upload
module & dc_log, heap-profile uploader, auth-diagnostics uploader,
session-analytics halves of feedback; local zero-egress observability
preserved in new kigi-log crate (unified log, --debug firehose,
subsystem file logs, opt-in instrumentation)
- announcements (crate, remote-settings fields, TUI surfaces)
- plugin marketplace (crate, sources/browse/CTA/extensions-modal tab);
direct plugin install/uninstall/update via kigi-agent git_install kept
- relay/gateway/assets endpoints and features (agent relay, headless
relay transport, gateway bridge, LeaderEnvUrls); leader IPC socket now
~/.kigi/leader.sock + KIGI_LEADER_SOCKET, no ws-url derivation
- functional types rehomed instead of deleted: PermissionMode ->
kigi-config-types, McpInitStrategy -> kigi-mcp, PrCreationSource ->
session signals, TerminalDiagnostics -> kigi-pager-render, agent_id ->
shell util
Endpoints
- kigi-env rewritten: single production KigiEndpoints {coding_api_base_url
https://api.kimi.com/coding/v1 (KIGI_CODE_BASE_URL), oauth_host
https://auth.kimi.com (KIGI_OAUTH_HOST), update_base_url (GitHub
Releases API), upgrade_page_url}; GrokBuildEnvironment enum deleted
Toolchain & workspace hygiene
- Rust 1.97.0 pinned; edition 2024; full cargo update; git2 hoisted to
workspace at 0.21 (Option->Result API migration), quick-xml 0.41
- Root Cargo.toml hand-maintained (PRD §8.1): version 0.1.0 inherited by
all members, members sorted, unused deps pruned
- cargo-deny advisories gate (deny.toml with documented transitive
exceptions); CI workflow (check/clippy/fmt/deny/test, macOS+Linux)
- cross-crate test seams re-gated behind `test-support` cargo feature;
insta snapshot baselines renamed to the kigi_tui prefix
- clippy --workspace --all-targets: zero warnings; fmt clean
Fixes surfaced by the port
- updater probe/installer divergence (bin/kigi vs bin/grok symlink set)
- idle model-metadata refresh dead under KIGI_CODE_BASE_URL override
(new is_effective_coding_endpoint_url, loopback+override aware)
- macOS symlinked-TMPDIR fixture canonicalization (foreign_sessions,
fast-worktree); RSS measurement tests serialized via serial_test
Docs & legal (Apache §4)
- NOTICE added (upstream attribution + change statement); THIRD-PARTY
notices sustained; kigi-tools ported-code notices extended; README,
CONTRIBUTING, SECURITY, AGENTS.md rewritten
Out of scope for M0 (tracked): Kimi auth/inference (M1), search/fetch,
command parity, config import (M2), Computer Hub excision & final
brand-token sweep (M2), distribution & self-update rewrite (M3).
230 lines
8.6 KiB
Markdown
230 lines
8.6 KiB
Markdown
# Project Rules (AGENTS.md)
|
|
|
|
Project rules let you configure Grok per project or directory. By placing an AGENTS.md file in your repository, you can set coding conventions, build instructions, style guides, and any other instructions that Grok should follow when working in that codebase.
|
|
|
|
---
|
|
|
|
## What Are Project Rules?
|
|
|
|
Project rules are Markdown files that Grok reads and adds to its context. Grok follows their content for every interaction in that tree.
|
|
|
|
This is the primary mechanism for teaching Grok about your project's conventions, so you need not restate them each session.
|
|
|
|
---
|
|
|
|
## Supported File Names
|
|
|
|
Grok checks for these filenames (in this order) within each directory:
|
|
|
|
- `Agents.md`
|
|
- `Claude.md`
|
|
- `CLAUDE.md`
|
|
- `CLAUDE.local.md`
|
|
- `AGENT.md`
|
|
- `AGENTS.md`
|
|
|
|
Grok loads every matching file in a directory, so a folder that contains both `AGENTS.md` and `CLAUDE.md` contributes both. On case-insensitive filesystems, names that resolve to the same file (such as `Agents.md` and `AGENTS.md`) are deduplicated and counted once. `Claude.md`, `CLAUDE.md`, and `CLAUDE.local.md` are supported for compatibility with Claude Code workflows. When Claude compatibility is enabled (the default), Grok also scans your home-level `~/.claude/` directory for these filenames and, at each directory level, checks `.claude/CLAUDE.md` and `.claude/CLAUDE.local.md` -- the locations Claude Code uses for project memory. With Cursor compatibility enabled, the home-level `~/.cursor/` directory is scanned the same way.
|
|
|
|
### Rules Directories
|
|
|
|
In addition to AGENTS.md files, Grok scans for `*.md` files in rules directories at each level (`<dir>`) from the repo root to the current working directory:
|
|
|
|
| Location | Notes |
|
|
|----------|-------|
|
|
| `<dir>/.kigi/rules/` | Always scanned |
|
|
| `<dir>/.claude/rules/` | Claude compatibility (configurable) |
|
|
| `<dir>/.cursor/rules/` | Cursor compatibility (configurable) |
|
|
|
|
Grok scans the Claude and Cursor rules directories by default. To disable scanning for a specific vendor, set its cell in the `[compat]` config section or the corresponding environment variable. See [Configuration](05-configuration.md#harness-compatibility) for details.
|
|
|
|
---
|
|
|
|
## How Discovery Works
|
|
|
|
Grok scans for project rules in this order:
|
|
|
|
1. **Global rules**: `~/.kigi/` (applies to all projects)
|
|
2. **Repo rules**: If inside a git repo, every directory from the repo root down to the current working directory (inclusive)
|
|
3. **CWD-only**: If not inside a git repo, only the current working directory
|
|
|
|
### Example
|
|
|
|
Given this project structure:
|
|
|
|
```
|
|
~/projects/my-app/
|
|
AGENTS.md # "Use TypeScript. Follow ESLint rules."
|
|
src/
|
|
AGENTS.md # "Prefer functional components."
|
|
components/
|
|
AGENTS.md # "Use CSS modules for styling."
|
|
```
|
|
|
|
When Grok runs in `~/projects/my-app/src/components/`, it loads all three files. The instructions accumulate, so Grok sees all of them.
|
|
|
|
### Deeper Files Take Precedence
|
|
|
|
Grok orders the files from the repo root to the current working directory, so files in deeper directories appear later in its context and take precedence when instructions conflict. In the example above, if the root says "Use styled-components" but `components/AGENTS.md` says "Use CSS modules", the CSS modules instruction wins because it appears later.
|
|
|
|
### Auto-Loading Behavior
|
|
|
|
- Grok loads the files from the repo root to the current working directory automatically at session start.
|
|
- When Grok reads, lists, or edits files in directories outside that initial set, it detects any project instruction files there, notes their paths, and reads them when they apply to the task.
|
|
|
|
---
|
|
|
|
## What to Put in Project Rules
|
|
|
|
### Coding Conventions
|
|
|
|
```markdown
|
|
# Coding Standards
|
|
|
|
- Use TypeScript for all new code
|
|
- Prefer functional components with hooks over class components
|
|
- Use `const` by default; only use `let` when reassignment is needed
|
|
- Maximum line length: 100 characters
|
|
```
|
|
|
|
### Build and Test Instructions
|
|
|
|
```markdown
|
|
# Build & Test
|
|
|
|
- Run `npm test` before committing
|
|
- Use `npm run lint` to check code style
|
|
- Build with `npm run build` -- ensure no TypeScript errors
|
|
- Integration tests: `npm run test:e2e` (requires Docker)
|
|
```
|
|
|
|
### Style Guides
|
|
|
|
```markdown
|
|
# Style Guide
|
|
|
|
- Follow the Airbnb JavaScript Style Guide
|
|
- Use 2-space indentation
|
|
- Always use trailing commas in multi-line arrays/objects
|
|
- Prefer template literals over string concatenation
|
|
```
|
|
|
|
### PR and Commit Requirements
|
|
|
|
```markdown
|
|
# Version Control
|
|
|
|
- Write commit messages in conventional commits format
|
|
- Prefix branch names with `feature/`, `fix/`, or `chore/`
|
|
- All PRs require at least one approval before merge
|
|
- Squash-merge feature branches
|
|
```
|
|
|
|
### Architecture Notes
|
|
|
|
```markdown
|
|
# Architecture
|
|
|
|
- API routes go in `src/routes/` with one file per resource
|
|
- Business logic goes in `src/services/`
|
|
- Database queries go in `src/repositories/`
|
|
- Never import from `src/routes/` in `src/services/`
|
|
```
|
|
|
|
---
|
|
|
|
## Scoping Rules to Subdirectories
|
|
|
|
AGENTS.md files scope to the entire directory tree rooted at their folder. Use this to provide different instructions for different parts of your codebase:
|
|
|
|
```
|
|
my-monorepo/
|
|
AGENTS.md # Monorepo-wide rules
|
|
packages/
|
|
frontend/
|
|
AGENTS.md # "Use React. Prefer CSS modules."
|
|
backend/
|
|
AGENTS.md # "Use Express. Follow REST conventions."
|
|
shared/
|
|
AGENTS.md # "No framework-specific code in this package."
|
|
```
|
|
|
|
---
|
|
|
|
## Session Rules Flags
|
|
|
|
To add rules for a single session without editing files, pass `--rules` (alias `--append-system-prompt`):
|
|
|
|
```bash
|
|
grok --rules "Always use TypeScript. Prefer functional components."
|
|
```
|
|
|
|
Grok appends this text to the session's system prompt. Use it for session-specific customization.
|
|
|
|
To replace the system prompt entirely, pass `--system-prompt-override` (alias `--system-prompt`). Grok uses the text verbatim and skips both the default system prompt and `--rules`. (Text passed with `--rules`, by contrast, is wrapped in a `<human_rules>` block and appended to the default prompt.)
|
|
|
|
---
|
|
|
|
## File Size
|
|
|
|
Grok loads each project instruction file in full; there is no character cap and no truncation. Even so, keep instructions concise and focused. Shorter, specific rules are easier for Grok to follow than long ones, and every file you load consumes context.
|
|
|
|
---
|
|
|
|
## Gitignore Filtering
|
|
|
|
Files ignored by `.gitignore` are skipped during discovery. To keep personal overrides out of the shared repository, gitignore a recognized filename such as `CLAUDE.local.md`:
|
|
|
|
```gitignore
|
|
# .gitignore
|
|
CLAUDE.local.md
|
|
```
|
|
|
|
As top-level instruction files, Grok discovers only the recognized filenames listed under [Supported File Names](#supported-file-names) — not custom names such as `AGENTS.local.md` or `notes.md`. (Inside a rules directory such as `.kigi/rules/`, every `*.md` file is loaded regardless of name.)
|
|
|
|
---
|
|
|
|
## The .kigi/ Project Directory
|
|
|
|
Beyond AGENTS.md files, the `.kigi/` directory in your project root can contain additional project-level configuration:
|
|
|
|
| Path | Purpose |
|
|
|------|---------|
|
|
| `.kigi/config.toml` | Project-scoped MCP servers, plugins, and permission rules (other settings load only from `~/.kigi/config.toml`) |
|
|
| `.kigi/skills/` | Project-scoped skill definitions |
|
|
| `.kigi/plugins/` | Project-scoped plugins |
|
|
| `.kigi/agents/` | Project-scoped agent definitions |
|
|
| `.kigi/hooks/` | Project-scoped lifecycle hooks |
|
|
| `.kigi/lsp.json` | LSP server configuration |
|
|
|
|
These are all optional. See the respective guides for details on each.
|
|
|
|
---
|
|
|
|
## Inspecting Loaded Rules
|
|
|
|
Use `grok inspect` to see all loaded project instructions:
|
|
|
|
```bash
|
|
grok inspect
|
|
```
|
|
|
|
This shows each project instruction file it finds, with its path and approximate token count. Use it to confirm Grok picks up your rules.
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
1. **Start with the root.** Put the most important, project-wide rules in the repo root AGENTS.md.
|
|
|
|
2. **Be specific.** "Use TypeScript" is better than "Use modern JavaScript". "Run `cargo fmt` before committing" is better than "Format your code".
|
|
|
|
3. **Keep it short.** Concise instructions are more likely to be followed than lengthy ones.
|
|
|
|
4. **Use subdirectory scoping for large repos.** Different parts of a monorepo may have different conventions. Use per-directory AGENTS.md to scope rules appropriately.
|
|
|
|
5. **Version control your rules.** Commit AGENTS.md to the repository so the whole team benefits. User-specific overrides belong in `~/.kigi/` (global rules).
|
|
|
|
6. **Do not duplicate documentation.** AGENTS.md should contain actionable instructions, not a copy of your project's README. Link to external docs if needed.
|
|
|
|
7. **Review periodically.** As your project evolves, update your rules to match current conventions.
|