CLI coding with grok or agy

CLI coding with grok or agy

Default: if grok or agy can do the task, use the CLI. Do this whenever possible, not only when the user asks.

When the task is to write, change, debug, or deeply investigate code, including continuing a prior grok/agy coding session in the same project, do not edit the codebase yourself. Run this skill first and hand the coding work to grok or agy CLI (whichever is available and signed in). Prefer this over direct file edits, hand-rolled patches, and ad-hoc shell sed/python rewrites of project source.

Cloud / remote coding agents are a fallback only when neither CLI can run the job (missing install, not logged in, CLI errors out, or the work must run off this machine).

1. Pick a CLI

Ensure PATH includes common install locations (e.g. ~/.local/bin, ~/.grok/bin).

If both are available and signed in, use grok first; on hard failure, retry once with agy. agy is coding-only — never send it general questions, web search, or non-code chat.

2. Continue a previous session

If this is a follow-up, correction, or “keep going” on work already done with this CLI in the same project directory, resume — do not start a blank session. A new project directory means a new session.

grok

Use the same --cwd. Prefer -c / --continue with the follow-up prompt. Use either --prompt-file or -p / --single, never both.

grok --always-approve --permission-mode bypassPermissions \
  --cwd "$PROJECT_DIR" \
  -c -p "follow-up"

Longer follow-ups:

grok --always-approve --permission-mode bypassPermissions \
  --cwd "$PROJECT_DIR" \
  -c \
  --prompt-file /tmp/cli-coding-prompt.md \
  --output-format plain

If you have a session id from grok sessions list in that directory, -r / --resume <SESSION_ID_OR_TITLE> is the precise form (UUID = id). Omitting the id resumes the most recent session for that cwd.

From the project directory:

grok sessions list -n 20
grok sessions search QUERY

grok sessions list prints SESSION ID. After a run you expect to continue later, note that id (do not print secrets). Do not pass --fork-session or --restore-code unless the user asks.

agy

Rerun from the same project directory with --print and either -c / --continue (most recent) or --conversation <id> (specific).

cd "$PROJECT_DIR"
agy --print --dangerously-skip-permissions \
  --print-timeout 15m \
  --continue \
  "$(cat /tmp/cli-coding-prompt.md)"

Specific conversation:

cd "$PROJECT_DIR"
agy --print --dangerously-skip-permissions \
  --print-timeout 15m \
  --conversation "$ID" \
  "$(cat /tmp/cli-coding-prompt.md)"

3. Scope the task (do not implement yet)

Before launching the CLI, gather only enough to write a good prompt:

• Repo / working directory (absolute path on this computer)
• Goal and success criteria
• Constraints (no secrets in logs, don’t commit unless asked, don’t touch unrelated areas)
• Relevant file paths or symbols if already known — as hints, not a line-by-line prescription

Do not root-cause and rewrite the code yourself. The CLI agent investigates and implements.

4. Write a prompt file

Put the full task in a temp markdown file (e.g. /tmp/cli-coding-prompt.md) so shell quoting never truncates it.

Prompt shape:

1. Goal — what to build or fix
2. Context — repo layout, important files, APIs to mirror
3. Requirements — concrete behavior, edge cases
4. Out of scope — what not to change
5. Done when — checks to run (node --check, tests, rg for a symbol, etc.) and a short summary to print

Tell the CLI to implement, verify, and summarize; tell it not to commit unless the user asked.

5. Run headless (non-interactive)

Work in the project directory. Prefer long enough block/timeout for multi-file work. Tee output to a log under /tmp for review.

If this is a follow-up in the same directory, use section 2 instead of a blank session.

grok

Use either --prompt-file or -p / --single, never both.

export PATH="$HOME/.local/bin:$HOME/.grok/bin:$PATH"
grok --always-approve --permission-mode bypassPermissions \
  --cwd "$PROJECT_DIR" \
  --prompt-file /tmp/cli-coding-prompt.md \
  --output-format plain

Short one-liners only:

grok --always-approve --permission-mode bypassPermissions \
  --cwd "$PROJECT_DIR" \
  -p "…"

Web search/fetch is on by default. Pass --disable-web-search only when you must stay offline.

agy

export PATH="$HOME/.local/bin:$HOME/.grok/bin:$PATH"
cd "$PROJECT_DIR"
agy --print --dangerously-skip-permissions \
  --print-timeout 15m \
  "$(cat /tmp/cli-coding-prompt.md)"

(Adjust flags if agy --help differs on this install; keep print/non-interactive + auto-approve permissions.)

6. After the CLI finishes

1. Read the CLI summary / log.
2. Verify yourself with read-only checks (syntax, tests, rg for new symbols, smoke scripts) — do not re-implement.
3. If the CLI left gaps, resume with a follow-up (section 2) — same CLI, same project directory.
4. If you will likely continue later, from that cwd run grok sessions list -n 20 and note the SESSION ID (do not print secrets).
5. Only edit files yourself for tiny verify-only fixes (typo in a path, chmod) when a full CLI round-trip is clearly wasteful — and say so. Anything substantive goes back to the CLI.
6. Deliver results to the user in plain language: what changed, how to use it, what was verified.

7. Hard rules

• Prefer grok or agy whenever they can do the coding task, not only when the user says to use the CLI.
• Prioritize this skill whenever the user asks for coding help, even if a cloud-coding skill also applies — run the CLI path first unless they name the other path.
• agy is coding-only. Never recommend or run agy for general questions, web search, or non-code chat.
• Never paste bot tokens, API keys, webhook secrets, or auth files into the prompt or chat.
• Don’t commit or push unless the user asked.
• Don’t claim the CLI did work you didn’t actually run.
• Do not pass --fork-session or --restore-code unless the user asks.
• If the user says “don’t code directly” / “use grok/agy”, that overrides any habit of patching files inline.