bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(cheatsheets): add Devin/Claude/Codex CLI cheat sheets

Browse Source 
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.
This commit is contained in:
saravanakumardb1 2026-05-28 19:42:07 -07:00
parent 8738d07da7
commit f0911e65ed
4 changed files with 479 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
AI.dev/CHEATSHEETS/README.md Normal file
View File

@ -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 <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_

127
AI.dev/CHEATSHEETS/claude-code-cli.md Normal file
View File

@ -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:** <https://docs.anthropic.com/en/docs/claude-code>
---
## 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 <id> "<prompt>" # 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: <paths>. Tests are sacred; fix code, not tests.
Verify: pnpm --filter <pkg> 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`)._

128
AI.dev/CHEATSHEETS/codex-cli.md Normal file
View File

@ -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:** <https://developers.openai.com/codex/cli> · source: <https://github.com/openai/codex>
---
## 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: <paths> only. Tests are sacred. No console.log. productId on Cosmos docs.
Verify: pnpm --filter <pkg> 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`)._

126
AI.dev/CHEATSHEETS/devin-cli.md Normal file
View File

@ -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:** <https://docs.devin.ai>
---
## 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 <id> # 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 <path>. Don't edit shared packages/.npmrc/docker-prep.sh.
Tests are sacred. Verify with: <exact commands>. 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 <id>` |
| 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 <name> # 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`)._