From f0911e65ed26b8d12ee432a9cd2df14c9862f609 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Thu, 28 May 2026 19:42:07 -0700 Subject: [PATCH] docs(cheatsheets): add Devin/Claude/Codex CLI cheat sheets 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. --- AI.dev/CHEATSHEETS/README.md | 98 ++++++++++++++++++++ AI.dev/CHEATSHEETS/claude-code-cli.md | 127 +++++++++++++++++++++++++ AI.dev/CHEATSHEETS/codex-cli.md | 128 ++++++++++++++++++++++++++ AI.dev/CHEATSHEETS/devin-cli.md | 126 +++++++++++++++++++++++++ 4 files changed, 479 insertions(+) create mode 100644 AI.dev/CHEATSHEETS/README.md create mode 100644 AI.dev/CHEATSHEETS/claude-code-cli.md create mode 100644 AI.dev/CHEATSHEETS/codex-cli.md create mode 100644 AI.dev/CHEATSHEETS/devin-cli.md diff --git a/AI.dev/CHEATSHEETS/README.md b/AI.dev/CHEATSHEETS/README.md new file mode 100644 index 00000000..537d5395 --- /dev/null +++ b/AI.dev/CHEATSHEETS/README.md @@ -0,0 +1,98 @@ +# 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 ` (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 ` --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 | | +| Claude Code | | +| Codex CLI | ยท | + +--- + +## 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.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 cheat sheet`. + +_Last updated: 2026-05-28_ diff --git a/AI.dev/CHEATSHEETS/claude-code-cli.md b/AI.dev/CHEATSHEETS/claude-code-cli.md new file mode 100644 index 00000000..01ae18df --- /dev/null +++ b/AI.dev/CHEATSHEETS/claude-code-cli.md @@ -0,0 +1,127 @@ +# ๐ŸŸฃ Claude Code CLI โ€” Cheat Sheet + +> **What it is:** Anthropic's **Claude Code** โ€” an agentic coding tool that runs in your +> terminal, reads/edits files, runs commands, and pair-programs interactively. +> **Best for:** Deep, multi-file changes where you want to stay in the loop โ€” reasoning +> through a refactor, debugging across modules, or building a feature with review at each step. +> **Per-repo rules:** reads `AGENTS.md` (canonical) and, if present, `CLAUDE.md`. + +> โš ๏ธ **Flags/commands drift between versions.** Confirm with `claude --help` and +> `/help` inside a session. +> +> **Official docs:** + +--- + +## Install & auth + +```bash +npm install -g @anthropic-ai/claude-code # or the documented installer +claude --version +claude # first run walks you through login +``` + +- Auth via Anthropic account (Pro/Max) or an `ANTHROPIC_API_KEY`. +- Config & history live under `~/.claude/`. + +## Launching + +```bash +claude # interactive REPL in the current dir +claude "explain src/server.ts and propose a refactor" # seed a first prompt +claude -p "list the failing tests" # print mode: one-shot, non-interactive +cat error.log | claude -p "what's the root cause?" # pipe context in +``` + +## Session management + +```bash +claude -c # continue the most recent conversation +claude --resume # pick a past session to resume +claude --resume "" # resume a specific session with a new instruction +``` + +Inside a session, history is preserved; use `/clear` to reset context when switching tasks. + +## Permission modes + +| How | Effect | +| -------------------------------- | ------------------------------------------------------- | +| _(default)_ | Prompts before edits / commands | +| `--permission-mode acceptEdits` | Auto-accepts file edits, still gates commands | +| `--permission-mode plan` | **Plan mode** โ€” proposes a plan, makes no changes | +| `--dangerously-skip-permissions` | Auto-approves **everything** (use only in a sandbox/VM) | + +```bash +claude --permission-mode plan # safe: get a plan first, no edits +claude --dangerously-skip-permissions # full auto โ€” only in throwaway/sandboxed env +``` + +> ๐Ÿง  Prefer **plan mode** for anything non-trivial: review the plan, then let it execute. +> Reserve `--dangerously-skip-permissions` for isolated environments (devcontainer/VM). + +## Useful in-session slash commands + +| Command | Purpose | +| --------------- | ------------------------------------------- | +| `/help` | List commands | +| `/clear` | Reset conversation context | +| `/init` | Generate/refresh a `CLAUDE.md` for the repo | +| `/review` | Review recent changes | +| `/model` | Switch model | +| `/agents` | Manage subagents | +| `/mcp` | Inspect/connect MCP servers | +| `#` (prefix) | Add a durable memory to `CLAUDE.md` | +| `@path/to/file` | Pull a file into context | + +## Config files & memory + +- **`AGENTS.md`** (repo root) โ€” canonical agent rules; Claude reads it. +- **`CLAUDE.md`** โ€” optional Claude-specific memory; `/init` scaffolds it, `#` appends to it. +- **`.claude/settings.json`** (repo or `~/.claude/`) โ€” permissions, hooks, tools, MCP. +- **MCP servers** โ€” connect tools/data via `claude mcp add ...` or `.mcp.json`. + +## ByteLyst workflow + +Open every delegation with the shared guardrails โ€” Claude honors `AGENTS.md`, but +re-stating scope keeps it tight: + +```text +Follow AGENTS.md + AI.dev/SKILLS/agent-behavior-guidelines.md. +Scope: . Tests are sacred; fix code, not tests. +Verify: pnpm --filter typecheck && ... test && ... build (next build --webpack). +pnpm workspace; @bytelyst/* link via workspace:*. Conventional commits, one per logical change. +Use plan mode first for multi-file work; show the plan before editing. +``` + +- Use `/review` before committing a cluster of edits. +- For repo onboarding context, run `/init` once and commit the resulting `CLAUDE.md` + (keep it thin โ€” it should point at `AGENTS.md`, not duplicate it). + +## Troubleshooting + +| Symptom | Fix | +| ---------------------------- | ------------------------------------------------------------------------------------- | +| Edits applied without asking | You're in `acceptEdits`/`--dangerously-skip-permissions`; switch to default or `plan` | +| Context bloated / confused | `/clear` and re-seed with `@` file references | +| Can't reach Gitea/registry | Corp proxy must be active (`NETWORK=corp`); workspace deps avoid the registry | +| Build fails on Turbopack | Use `next build --webpack` | +| Wants a tool it can't access | Wire it via MCP (`/mcp`, `claude mcp add`) | + +## Quick-reference card + +```text +claude # interactive +claude -p "..." # one-shot print mode +claude -c # continue last session +claude --resume # pick a session +claude --permission-mode plan # plan first, no edits +/init /clear /review /model /mcp #memory @file +``` + +--- + +**Related:** [`devin-cli.md`](./devin-cli.md) ยท [`codex-cli.md`](./codex-cli.md) ยท +[`../PROMPTS/`](../PROMPTS/) ยท [`../SKILLS/agent-behavior-guidelines.md`](../SKILLS/agent-behavior-guidelines.md) + +_Last updated: 2026-05-28 ยท verify flags against your installed version (`claude --help`)._ diff --git a/AI.dev/CHEATSHEETS/codex-cli.md b/AI.dev/CHEATSHEETS/codex-cli.md new file mode 100644 index 00000000..4b5e0204 --- /dev/null +++ b/AI.dev/CHEATSHEETS/codex-cli.md @@ -0,0 +1,128 @@ +# ๐ŸŸข Codex CLI โ€” Cheat Sheet + +> **What it is:** OpenAI's **Codex CLI** โ€” an open-source terminal coding agent that +> edits files and runs commands inside a built-in sandbox, interactively or as a +> scriptable one-shot (`codex exec`). +> **Best for:** Fast local edits, and **automation** โ€” `codex exec` slots cleanly into +> CI / Gitea Actions and one-shot scripts. +> **Per-repo rules:** reads `AGENTS.md` (merged with `~/.codex/AGENTS.md` and any +> project-local `AGENTS.md`). +> **In this repo:** delegation examples live under +> [`docs/ecosystem/delegation/codex/`](../../docs/ecosystem/delegation/codex/) and +> [`docs/CODEX_RESUME_PROMPT.md`](../../docs/CODEX_RESUME_PROMPT.md). + +> โš ๏ธ **Flags/modes drift between versions.** Confirm with `codex --help`. +> +> **Official docs:** ยท source: + +--- + +## Install & auth + +```bash +npm install -g @openai/codex # or: brew install codex +codex --version +codex login # ChatGPT sign-in, or set OPENAI_API_KEY +``` + +- Config & state live under `~/.codex/` (notably `~/.codex/config.toml`). + +## Launching + +```bash +codex # interactive TUI in the current dir +codex "add a vitest for src/lib/utils.ts" # seed the first instruction +codex exec "run the test suite and fix failures" # non-interactive one-shot (scripts/CI) +codex resume # resume a previous session +``` + +## Approval + sandbox modes + +Codex couples **what it can touch** (sandbox) with **when it asks** (approvals). + +| Flag | Meaning | +| ------------------------------------------------------------------------- | ------------------------------------------------------------------ | +| `--sandbox read-only` | Can read; no writes, no commands | +| `--sandbox workspace-write` | Can edit the working dir + run commands in it (default-ish) | +| `--sandbox danger-full-access` | No sandbox restrictions | +| `--ask-for-approval untrusted` \| `on-failure` \| `on-request` \| `never` | When to prompt you | +| `--full-auto` | Convenience: low-friction auto (workspace-write + minimal prompts) | +| `--dangerously-bypass-approvals-and-sandbox` | **No approvals, no sandbox** (CI/throwaway only) | + +```bash +codex --full-auto # everyday autonomy, still sandboxed +codex --sandbox workspace-write --ask-for-approval on-failure +codex exec --dangerously-bypass-approvals-and-sandbox "..." # CI only, isolated runner +``` + +> ๐Ÿง  The sandbox is **built in** (unlike Devin's optional `--sandbox`). For ByteLyst, +> `workspace-write` is fine for single-package work, but cross-package `workspace:*` +> builds and the corp proxy / Gitea tunnel may need broader access โ€” prefer running from +> the monorepo root and, if installs fail, loosen the sandbox rather than fighting it. + +## Config (`~/.codex/config.toml`) + +```toml +model = "..." # default model +approval_policy = "on-failure" +sandbox_mode = "workspace-write" +# [mcp_servers.*] # wire external tools via MCP +``` + +Project-level `AGENTS.md` is layered on top of `~/.codex/AGENTS.md`. + +## `codex exec` for automation (the high-value mode) + +```bash +# One-shot, non-interactive โ€” perfect for Gitea Actions / scripts: +codex exec "typecheck the repo and fix any TS errors" \ + --sandbox workspace-write --ask-for-approval never +``` + +- Deterministic, no TUI; exits with a status you can gate CI on. +- Pair with a tight prompt + explicit verify commands (see below). + +## ByteLyst workflow + +Lead with the shared guardrails (Codex reads `AGENTS.md`, but restate scope): + +```text +Follow AGENTS.md + AI.dev/SKILLS/agent-behavior-guidelines.md. +Scope: only. Tests are sacred. No console.log. productId on Cosmos docs. +Verify: pnpm --filter typecheck && ... test && ... build (next build --webpack). +pnpm workspace; @bytelyst/* via workspace:*. Conventional commits, one per change. +Only mark done after verify passes; never fabricate results. +``` + +- Start in `read-only` for a plan, then switch to `workspace-write` to execute. +- Reserve `--dangerously-bypass-approvals-and-sandbox` for the isolated CI runner. + +## Troubleshooting + +| Symptom | Fix | +| ------------------------------------- | ------------------------------------------------------------------------------- | +| "permission denied" writing files | Sandbox is `read-only`; use `--sandbox workspace-write` | +| Can't build `@bytelyst/*` deps | Sandbox can't see sibling `packages/*` โ€” run from monorepo root, loosen sandbox | +| Network/registry errors | Corp proxy must be active; workspace deps avoid the registry | +| `next build` fails (Turbopack) | Use `next build --webpack` | +| Non-interactive run hangs on a prompt | Add `--ask-for-approval never` to `codex exec` | + +## Quick-reference card + +```text +codex # interactive +codex "..." # seed an instruction +codex exec "..." # one-shot (CI/scripts) +codex resume # resume session +--sandbox read-only|workspace-write|danger-full-access +--ask-for-approval untrusted|on-failure|on-request|never +--full-auto # convenient autonomy (still sandboxed) +~/.codex/config.toml # defaults: model, approval_policy, sandbox_mode +``` + +--- + +**Related:** [`devin-cli.md`](./devin-cli.md) ยท [`claude-code-cli.md`](./claude-code-cli.md) ยท +[`../PROMPTS/`](../PROMPTS/) ยท [`../SKILLS/agent-behavior-guidelines.md`](../SKILLS/agent-behavior-guidelines.md) + +_Last updated: 2026-05-28 ยท verify flags against your installed version (`codex --help`)._ diff --git a/AI.dev/CHEATSHEETS/devin-cli.md b/AI.dev/CHEATSHEETS/devin-cli.md new file mode 100644 index 00000000..d1959347 --- /dev/null +++ b/AI.dev/CHEATSHEETS/devin-cli.md @@ -0,0 +1,126 @@ +# ๐Ÿค– Devin CLI โ€” Cheat Sheet + +> **What it is:** Cognition's **Devin** as a terminal agent. You hand it a scoped task +> (ideally a self-contained roadmap), and it plans โ†’ edits โ†’ runs โ†’ verifies across many +> steps with minimal babysitting. +> **Best for:** Long-running, well-scoped delegations where you want to walk away โ€” e.g. +> "validate and harden `tracker-web`'s test suite," or "execute this 5-task roadmap." +> **In this repo:** session config lives in `.devin/config.local.json` (**secret โ€” never +> commit or print it**). A worked example is +> [`dashboards/tracker-web/docs/roadmaps/DEVIN_CLI_EXPERIMENT.md`](../../dashboards/tracker-web/docs/roadmaps/DEVIN_CLI_EXPERIMENT.md). + +> โš ๏ธ **Flags drift between versions.** Run `devin --help` to confirm. This sheet captures +> the workflow + ByteLyst conventions, which are stable. +> +> **Official docs:** + +--- + +## Install & auth + +```bash +# Install per the official docs (https://docs.devin.ai), then verify + authenticate. +# (Confirm the exact subcommands for your version with `devin --help`.) +devin --help # list available commands/flags +devin login # authenticate (or provide the API key Devin expects) +``` + +- Auth/state for this workspace is cached in `.devin/config.local.json` (mode `600`). +- That file may contain an **API token** โ†’ it is git-ignored; keep it that way. + +## Launching a session + +```bash +devin # interactive TUI in the current dir +devin "validate the tracker-web tests" # seed the first instruction inline +``` + +A Devin session shows a live **todo list** and streams its tool calls (reads, edits, +shell commands). You can interrupt at any time (Ctrl-C / Esc) โ€” that shows up in the +log as `Canceled due to user interrupt` (this is **you**, not a permission block). + +## Permission & sandbox modes + +| Flag | Effect | +| ----------------------------- | ------------------------------------------------------------- | +| _(default)_ | Asks before potentially destructive commands | +| `--permission-mode dangerous` | **Auto-approves** commands without prompting | +| `--sandbox` | Runs in an **isolated environment** (restricted fs / network) | + +```bash +# Full autonomy, isolated: +devin --permission-mode dangerous --sandbox + +# Full autonomy, direct access to the real pnpm workspace + corp proxy: +devin --permission-mode dangerous +``` + +> ๐Ÿง  **Gotcha (learned the hard way):** `--sandbox` can wall off the filesystem and +> network even when command _approval_ is automatic. ByteLyst work needs to (a) read +> sibling `packages/*` for `workspace:*` builds and (b) reach the corp proxy / Gitea +> tunnel for `pnpm`. If a sandboxed run stalls on install/build, **drop `--sandbox`**. +> `dangerous` mode never blocks; a stall is almost always sandbox scope. + +## Session management + +```bash +devin -r # list recent sessions +devin -r # resume a specific session (e.g. `devin -r adaptable-comma`) +/exit # leave the interactive session +``` + +Sessions are named (e.g. `adaptable-comma`); the CLI prints the resume command when you +exit. Resuming keeps the prior context + todo state. + +## How to delegate well (the ByteLyst pattern) + +Devin shines with a **self-contained roadmap file**. Don't free-form a vague goal โ€” +point it at a doc that encodes scope, verify commands, and a done-definition. See +[`AI.dev/PROMPTS/`](../PROMPTS/) for reusable templates and the tracker-web experiment +doc for the gold-standard shape: + +1. **Scope lock** โ€” name the exact folder; forbid edits elsewhere (incl. shared packages). +2. **Verify commands** โ€” give the literal `pnpm typecheck && pnpm lint && pnpm test && pnpm build`. +3. **Commit discipline** โ€” one task = one conventional commit; flip the checkbox + paste + the short-SHA in the same commit. +4. **No fabrication** โ€” only check a box after its Verify passes; otherwise leave `- [ ]` + with a one-line blocker. +5. **Done-definition** โ€” full suite green from a clean state + a summary of SHAs. + +Paste this preamble into the first instruction every time: + +```text +Read AGENTS.md and AI.dev/SKILLS/agent-behavior-guidelines.md first. +Scope: ONLY . Don't edit shared packages/.npmrc/docker-prep.sh. +Tests are sacred. Verify with: . Conventional commits. +Builds use `next build --webpack`. pnpm workspace; workspace:* deps link locally. +Only mark a task done after its verify passes โ€” never fabricate. Commit + push per task. +``` + +## Troubleshooting + +| Symptom | Likely cause | Fix | +| ----------------------------------------------- | ---------------------------------------------------- | ------------------------------------------ | +| `Canceled due to user interrupt` | You pressed Ctrl-C/Esc or `/exit` | Resume: `devin -r ` | +| Stalls on `pnpm install` / build in `--sandbox` | Sandbox blocks fs/network | Re-run **without** `--sandbox` | +| Can't find `@bytelyst/*` packages | Sandbox can't see sibling `packages/*` | Run from the monorepo; drop `--sandbox` | +| `pnpm` network errors | Corp proxy / Gitea tunnel not reachable from sandbox | Run on host (proxy active) without sandbox | +| Asks for approval despite `dangerous` | Flag typo / older binary | `devin --help`; update the CLI | + +## Quick-reference card + +```text +devin # start interactive session here +devin --permission-mode dangerous # auto-approve commands (recommended for delegations) + add --sandbox # ...but only if the task needs no workspace/network +devin -r # list sessions +devin -r # resume a session +/exit # end session (prints resume command) +``` + +--- + +**Related:** [`claude-code-cli.md`](./claude-code-cli.md) ยท [`codex-cli.md`](./codex-cli.md) ยท +[`../PROMPTS/`](../PROMPTS/) ยท [`../SKILLS/agent-behavior-guidelines.md`](../SKILLS/agent-behavior-guidelines.md) + +_Last updated: 2026-05-28 ยท verify flags against your installed version (`devin --help`)._