f0911e65ed
New AI.dev/CHEATSHEETS/ reference set for delegating to terminal AI agents: - README.md: comparison matrix, 'which CLI?' decision guide, official-docs links, cross-CLI rules + ByteLyst environment facts - devin-cli.md: sessions, --permission-mode dangerous vs --sandbox, resume, the sandbox-stall gotcha, delegation pattern + prompt preamble - claude-code-cli.md: REPL/-p/-c/--resume, permission+plan modes, slash commands, MCP - codex-cli.md: interactive vs codex exec for CI, sandbox x approval matrix, config.toml Flags hedged with 'confirm via --help' since they drift between versions; durable value is the ByteLyst workflow. Does not reference .devin/config.local.json contents.
99 lines
5.9 KiB
Markdown
99 lines
5.9 KiB
Markdown
# AI Coding CLI Cheat Sheets
|
|
|
|
> **Location:** `AI.dev/CHEATSHEETS/`
|
|
> **Audience:** Every developer in the ByteLyst ecosystem who delegates work to a
|
|
> terminal-based AI coding agent.
|
|
> **Companion docs:** [`../SKILLS/`](../SKILLS/) (how-to skills), [`../PROMPTS/`](../PROMPTS/)
|
|
> (reusable copy-paste prompts), and the canonical
|
|
> [`../SKILLS/agent-behavior-guidelines.md`](../SKILLS/agent-behavior-guidelines.md)
|
|
> (the rules every agent must follow, regardless of which CLI runs it).
|
|
|
|
---
|
|
|
|
## What's here
|
|
|
|
Quick, dense reference cards for the three terminal AI agents we use to delegate
|
|
coding work. Each sheet is **task-oriented** — commands, modes, session management,
|
|
config, and the ByteLyst-specific guardrails — not a marketing overview.
|
|
|
|
| CLI | Cheat sheet | Best for |
|
|
| ------------------ | -------------------------------------------- | ------------------------------------------------------------------------------- |
|
|
| 🤖 **Devin** | [`devin-cli.md`](./devin-cli.md) | Long-running autonomous sessions; delegate a scoped roadmap and walk away |
|
|
| 🟣 **Claude Code** | [`claude-code-cli.md`](./claude-code-cli.md) | Interactive pair-programming in the terminal; deep multi-file edits with review |
|
|
| 🟢 **Codex CLI** | [`codex-cli.md`](./codex-cli.md) | Fast local edits + scriptable `exec` runs in CI / one-shot automation |
|
|
|
|
---
|
|
|
|
## The 30-second mental model
|
|
|
|
| | Devin | Claude Code | Codex CLI |
|
|
| ----------------------- | ----------------------------- | -------------------------------- | --------------------------------------------------------------- |
|
|
| **Interaction** | Mostly fire-and-forget | Interactive REPL | Interactive **or** `exec` one-shot |
|
|
| **Strength** | Autonomy over many steps | Reasoning + careful edits | Speed + scripting |
|
|
| **Auto-approve flag** | `--permission-mode dangerous` | `--dangerously-skip-permissions` | `--dangerously-bypass-approvals-and-sandbox` (or `--full-auto`) |
|
|
| **Isolation** | `--sandbox` | OS sandbox / devcontainer | `--sandbox <mode>` (built-in) |
|
|
| **Per-repo rules file** | `AGENTS.md` | `AGENTS.md` (+ `CLAUDE.md`) | `AGENTS.md` |
|
|
| **Resume a session** | `devin -r [id]` | `claude --resume` / `-c` | `codex resume` |
|
|
|
|
> ⚠️ Exact flags drift between releases. **Always confirm with `<cli> --help`.** The
|
|
> durable value of these sheets is the ByteLyst workflow, not the flag spelling.
|
|
|
|
---
|
|
|
|
## Which CLI should I use?
|
|
|
|
- **Delegating a scoped, multi-step job and want to walk away?** → **Devin**. Point it at
|
|
a self-contained roadmap (see [`../PROMPTS/`](../PROMPTS/)) and let it run.
|
|
- **Working through a hard problem and want to review each move?** → **Claude Code** in
|
|
**plan mode** — it proposes, you approve, it executes.
|
|
- **Need a one-shot, scriptable run inside CI / Gitea Actions?** → **Codex CLI**
|
|
`codex exec` — non-interactive, exits with a status you can gate on.
|
|
- **Just making fast local edits?** → whichever you have open; **Codex** or **Claude Code**
|
|
interactive are both quick.
|
|
|
|
| Official docs | |
|
|
| ------------- | ----------------------------------------------------------------------------- |
|
|
| Devin | <https://docs.devin.ai> |
|
|
| Claude Code | <https://docs.anthropic.com/en/docs/claude-code> |
|
|
| Codex CLI | <https://developers.openai.com/codex/cli> · <https://github.com/openai/codex> |
|
|
|
|
---
|
|
|
|
## Rules that apply no matter which CLI you run
|
|
|
|
These come from [`../SKILLS/agent-behavior-guidelines.md`](../SKILLS/agent-behavior-guidelines.md)
|
|
and the per-repo `AGENTS.md`. Put them in the agent's opening prompt every time:
|
|
|
|
1. **Tests are sacred** — never delete/weaken a test to go green; fix the code.
|
|
2. **Verify before "done"** — only claim success after the real gate
|
|
(`typecheck` + `test` + `build`) passes. No fabricated results.
|
|
3. **Scope lock** — never hand-edit shared infra (`.npmrc`, `docker-prep.sh`),
|
|
and don't touch repos outside the task.
|
|
4. **No `console.log` / `print`** in product code.
|
|
5. **`productId` on every Cosmos document.**
|
|
6. **Conventional commits** — `type(scope): description`.
|
|
7. **Style preservation** — match the file's existing style; don't add emojis to code.
|
|
|
|
## ByteLyst environment facts every agent needs
|
|
|
|
- **Package manager:** `pnpm` workspace. Shared packages link via `workspace:*` /
|
|
`"*"` — no registry needed for local builds.
|
|
- **Next.js apps build with `next build --webpack`** (not plain/Turbopack).
|
|
- **Corporate network:** commands run behind a TLS-intercepting proxy
|
|
(`NETWORK=corp`). The Gitea npm registry is reached over an SSH tunnel at
|
|
`localhost:3300`. Gradle needs the custom truststore (`$GRADLE_OPTS`).
|
|
- **Monorepo root:** `learning_ai_common_plat` holds `packages/*`, `services/*`,
|
|
and `dashboards/*`. Product repos are siblings under the same parent.
|
|
|
|
---
|
|
|
|
## Adding / updating a cheat sheet
|
|
|
|
1. Edit or create `AI.dev/CHEATSHEETS/<cli>-cli.md`.
|
|
2. Keep the section order consistent across sheets (Install → Auth → Core commands
|
|
→ Modes → Sessions → Config → ByteLyst workflow → Troubleshooting → Quick card).
|
|
3. Add it to the table above.
|
|
4. Commit: `docs(cheatsheets): update <cli> CLI cheat sheet`.
|
|
|
|
_Last updated: 2026-05-28_
|