AGENTS.md

1# AGENTS.md - AI Agent Coding Guide
2 
3This guide is for AI coding agents working in the OpenClaude repository. Read it before changing code, and also follow [CONTRIBUTING.md](CONTRIBUTING.md) for contributor policy, PR expectations, review follow-up, and project scope.
4 
5## Project Snapshot
6 
7OpenClaude is a coding-agent CLI for cloud and local model providers. It supports OpenAI-compatible APIs, Anthropic, Gemini, DeepSeek, Ollama, MCP, local backends, slash commands, tools, agents, and a React/Ink terminal UI.
8 
9The installed CLI runs on Node.js `>=22.0.0`. Bun is used for source builds, scripts, dependency management, and tests.
10 
11## Work Style
12 
13- Keep changes focused on one problem.
14- Prefer existing patterns in the file or nearby module.
15- Avoid unrelated formatting, renames, dependency changes, or broad rewrites.
16- Add or update tests when behavior changes.
17- Update docs when setup, commands, provider behavior, or user-facing behavior changes.
18- For new features, larger refactors, dependencies, or runtime changes, follow the issue-first guidance in [CONTRIBUTING.md](CONTRIBUTING.md).
19 
20## Stack And Conventions
21 
22- TypeScript with strict mode and ESM imports.
23- React + Ink for terminal UI.
24- Bun lockfile and Bun scripts for development workflows.
25- Node runtime for the built CLI.
26 
27Common libraries and patterns:
28 
29- `chalk` for terminal color.
30- `commander` for CLI argument parsing.
31- `execa` for child processes.
32- Existing service, provider, settings, permission, and UI patterns over new abstractions.
33 
34## Repository Map
35 
36- `src/commands/` - slash and CLI command implementations.
37- `src/components/` - React/Ink UI components.
38- `src/services/` - API, MCP, OAuth, wiki, voice, and other service integrations.
39- `src/tools/` - tool implementations.
40- `src/utils/` - shared utilities.
41- `src/integrations/` - provider and model integration metadata.
42- `src/entrypoints/` - CLI, MCP, SDK, and generated public types.
43- `src/tasks/` - local, remote, workflow, and monitor task handling.
44- `docs/integrations/` - provider integration guidance.
45- `web/` - documentation website.
46 
47## Validation
48 
49Run the narrowest useful checks for your change, and list the exact commands in the PR.
50 
51Core checks:
52 
53```bash
54bun install
55bun run build
56bun run smoke
57bun run check
58bun run typecheck
59bun run typecheck:type-tests
60```
61 
62Focused checks:
63 
64```bash
65bun test ./path/to/test-file.test.ts
66bun run test:provider
67bun run test:provider-recommendation
68```
69 
70Web checks, when touching `web/`:
71 
72```bash
73bun run web:typecheck
74bun run web:build
75```
76 
77Diagnostics and PR hygiene:
78 
79```bash
80bun run doctor:runtime
81bun run security:pr-scan
82```
83 
84## Provider Changes
85 
86When modifying provider behavior:
87 
881. Start with `docs/integrations/overview.md`.
892. Use the relevant how-to guide under `docs/integrations/how-to/`.
903. Check existing provider implementations before adding a new pattern.
914. Test the exact provider/model path you changed when possible.
925. Avoid breaking third-party providers while fixing first-party behavior.
93 
94## Things To Avoid
95 
96- Do not change the Node runtime or Bun development workflow without prior maintainer agreement.
97- Do not add new Python code, Python provider paths, or Python dependencies without explicit maintainer approval.
98- Do not introduce dependencies without clear project benefit.
99- Do not skip tests for behavior changes.
100- Do not silently change provider tags; maintainers control them during review.
101- Do not ignore CodeRabbit or maintainer feedback; address it before requesting more review.
102