# Claude CLI

> This skill should be used when delegating general code tasks — explanations, refactors, fixes, analysis — via `claude -p`. Also use when context isolation or a specific Anthropic model is needed for the subtask.

- Skill: `namos2502/claude-cli` (Agent Skill)
- Install (CLI): `npx skillmds@latest add namos2502/claude-cli`
- Raw SKILL.md: https://api.skillmd.com/api/skills/namos2502/claude-cli/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: namos2502 (https://skillmd.com/u/namos2502)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/namos2502/claude-cli

---


# Claude CLI Agent

## When to Use

⛔ If the host is **Claude Code**: use Claude CLI only when you specifically need context isolation or a different Anthropic model AND native tools (Task tool, inline work) are insufficient. Claude Code → Claude CLI is last resort. Prefer Copilot CLI for GitHub tasks; prefer Claude Code's native Task tool for general code tasks.

---

**Use Claude CLI for:**
- General code tasks — explanations, refactors, fixes, analysis
- Tasks needing Anthropic-specific models (Sonnet, Opus, Haiku)
- Context isolation — offload long subtasks without polluting the host context
- Tasks where you want a different model than the host is running

**Do NOT use Claude CLI for:**
- GitHub-specific tasks (PRs, repos, Actions) — use Copilot CLI
- Tasks that need your current session context or open files
- When Claude CLI is not installed or not authenticated

## Core Flags

| Flag | Purpose |
|------|---------|
| `-p "PROMPT"` | Print mode — non-interactive, exits when done |
| `--output-format text` | Plain text output (default — easiest to parse) |
| `--output-format json` | Structured JSON with metadata |
| `--no-session-persistence` | Do not save session to disk — keeps scripted calls clean |
| `--max-turns N` | Cap agentic turns — prevents runaway tasks |
| `--bare` | Minimal mode: skip auto-discovery of hooks, skills, plugins, MCP servers, auto memory, and CLAUDE.md so scripted calls start faster. Claude has access to Bash, file read, and file edit tools |

## Tool Permissions

| Flag | Purpose |
|------|---------|
| `--allowedTools "TOOL"` | Tools that auto-execute without a permission prompt |
| `--disallowedTools "TOOL"` | Tools removed from the model's context entirely |

| Use case | Flags |
|----------|-------|
| Questions, analysis | `--allowedTools "Read"` |
| Modify existing files | `--allowedTools "Read" "Edit"` |
| Create + modify files | `--allowedTools "Read" "Edit" "Write"` |
| Create + modify files + run commands | `--allowedTools "Read" "Edit" "Write" "Bash(git *)"` |
| Explicitly block shell | `--disallowedTools "Bash"` |

`"Edit"` modifies existing files. `"Write"` creates new files — add it when the task may need to create files.

Shell access (`Bash(...)`) is a separate, deliberate decision. Use `--disallowedTools "Bash"` to prevent any shell execution, even if the model tries.

## Safety Flags

| Flag | Purpose |
|------|---------|
| `--max-budget-usd N` | Cap API spend (e.g. `--max-budget-usd 0.50`) |
| `--effort LEVEL` | Set the effort level: `low`, `medium`, `high`, `xhigh`, `max` — available levels depend on the model. Session-scoped, does not persist |
| `--permission-mode plan` | Read-only planning mode — no writes or shell, overrides `--allowedTools` |
| `--append-system-prompt "TEXT"` | Inject task-specific instructions into the system prompt |

## Model & Effort Selection

> Model IDs are versioned and change with releases. Run `claude models` to get current names.

| Task complexity | Model | Effort |
|-----------------|-------|--------|
| **Standard** — analysis, single fix | `--model sonnet` | *(default)* |
| **Complex** — multi-step, judgment calls | `--model sonnet` | `--effort high` *(or `xhigh`/`max`)* |
| Quick availability check / ping | `--model <fastest-available>` | *(default)* |

Use short aliases (`sonnet`, `opus`) for the latest version, or full IDs to pin a specific model. Omit `--effort` to use the model default. `--effort` is only available for Claude models — omit it when using non-Claude models. Complexity levels are defined in the orchestration skill.

## Working Directory

Claude CLI is sandboxed to its working directory — the same restriction as Copilot CLI.

⛔ **Always invoke from the repo root.** Use `--cwd` or `cd` before invoking.

```bash
claude -p "..." --cwd $(git rev-parse --show-toplevel) --output-format text ...
```

## Invocation Patterns

Always include `--append-system-prompt` with the CortexLink agent context below. This teaches the agent the report format and self-verify protocol via the system prompt — separate from the task prompt.

```
CORTEXLINK_AGENT_CONTEXT="You are operating as a CortexLink agent. Your output is consumed directly by a control center. Execute the task, verify your own work (Execute → Verify → fix if needed → Report), then return ONLY this structured report — plain text labels, no bold, no headers:\nSTATUS: ✅ Verified / ⚠️ Partial / ❌ Failed\nSUMMARY: <1-2 sentences>\nSTEPS:\n  - <step>\nFILES: <changed files or none>\nISSUES: <notes or none>\nMax 150 words. Never mark ✅ without actually checking. For analysis tasks, ✅ = completed the analysis even if you cannot run the code."
```

**Read-only delegation (question, analysis):**
```bash
claude -p "[delegation prompt]" --output-format text \
  --cwd $(git rev-parse --show-toplevel) \
  --allowedTools "Read" --model claude-haiku-4-5 \
  --no-session-persistence --max-turns 3 \
  --append-system-prompt "$CORTEXLINK_AGENT_CONTEXT"
```

**Write delegation (fix, implement):**
```bash
claude -p "[delegation prompt]" --output-format text \
  --cwd $(git rev-parse --show-toplevel) \
  --allowedTools "Read" "Edit" "Write" \
  --no-session-persistence \
  --append-system-prompt "$CORTEXLINK_AGENT_CONTEXT"
```

**Write delegation + shell (runs commands):**
```bash
claude -p "[delegation prompt]" --output-format text \
  --cwd $(git rev-parse --show-toplevel) \
  --allowedTools "Read" "Edit" "Write" "Bash(git *)" \
  --no-session-persistence \
  --append-system-prompt "$CORTEXLINK_AGENT_CONTEXT"
```

**Planning / analysis only (no writes):**
```bash
claude -p "[delegation prompt]" --output-format text \
  --cwd $(git rev-parse --show-toplevel) \
  --permission-mode plan --no-session-persistence --max-turns 5 \
  --append-system-prompt "$CORTEXLINK_AGENT_CONTEXT"
```

**Piped input:**
```bash
cat file.ts | claude -p "[delegation prompt]" --output-format text \
  --cwd $(git rev-parse --show-toplevel) \
  --allowedTools "Read" --no-session-persistence \
  --append-system-prompt "$CORTEXLINK_AGENT_CONTEXT"
```

## Delegation Prompt

Follow the template from `skills/orchestration/SKILL.md`. Include the structured report format instructions at the end of every prompt.

**Status semantics for analysis tasks:**
- ✅ Verified = you read the code and completed the analysis — even if you cannot *run* it
- ⚠️ Partial = you could not access required files, or the diff was truncated
- ❌ Failed = the `gh` command failed or the diff was inaccessible

⛔ Do NOT use ⚠️ just because you cannot execute the code being reviewed. Static analysis that is complete = ✅.

## Handling the Report

The agent's stdout is its report. Capture it directly:
```bash
REPORT=$(claude -p "[prompt]" --output-format text \
  --cwd $(git rev-parse --show-toplevel) \
  --allowedTools "Read" --no-session-persistence \
  --append-system-prompt "$CORTEXLINK_AGENT_CONTEXT" 2>/dev/null)
```

Read STATUS first. If ⚠️ or ❌, read ISSUES before deciding next action.

## Key Differences from Copilot CLI

| | Copilot CLI | Claude CLI |
|--|-------------|------------|
| Tool permissions | `--allow-tool='write, read'` | `--allowedTools "Read" "Edit"` |
| Prevent questions | `--no-ask-user` | implied by `-p` |
| Working directory | `cd $(git rev-parse --show-toplevel) &&` | `--cwd PATH` |
| Model flag | `--model=<model-id>` | `--model <model-id>` |

## Error Handling

| Failure | Action |
|---------|--------|
| Command not found | Tell user: `npm install -g @anthropic-ai/claude-code` |
| Auth failure | Tell user: `claude auth login` then re-run `/cortexlink:setup` |
| Budget exceeded | Increase `--max-budget-usd` or handle natively |
| Unexpected output | Retry once. If still failing, handle natively. |

## Chaining

Pass the SUMMARY + STEPS excerpt from this agent's report as [Context] in the next delegation prompt. Do not pass raw output.