Skip to main content
Delegate coding to Claude Code CLI (features, PRs).

Skill metadata

Reference: full SKILL.md

The following is the complete skill definition that Mibyan loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.

Claude Code — Mibyan Orchestration Guide

Delegate coding tasks to Claude Code (Anthropic’s autonomous coding agent CLI) via the Mibyan terminal. Claude Code v2.x can read files, write code, run shell commands, spawn subagents, and manage git workflows autonomously.

Prerequisites

  • Install: npm install -g @anthropic-ai/claude-code
  • Auth: run claude once to log in (browser OAuth for Pro/Max, or set ANTHROPIC_API_KEY)
  • Console auth: claude auth login --console for API key billing
  • SSO auth: claude auth login --sso for Enterprise
  • Check status: claude auth status (JSON) or claude auth status --text (human-readable)
  • Health check: claude doctor — checks auto-updater and installation health
  • Version check: claude --version (requires v2.x+)
  • Update: claude update or claude upgrade

Two Orchestration Modes

Mibyan interacts with Claude Code in two fundamentally different ways. Choose based on the task.

Mode 1: Print Mode (-p) — Non-Interactive (PREFERRED for most tasks)

Print mode runs a one-shot task, returns the result, and exits. No PTY needed. No interactive prompts. This is the cleanest integration path.
When to use print mode:
  • One-shot coding tasks (fix a bug, add a feature, refactor)
  • CI/CD automation and scripting
  • Structured data extraction with --json-schema
  • Piped input processing (cat file | claude -p "analyze this")
  • Any task where you don’t need multi-turn conversation
Print mode skips ALL interactive dialogs — no workspace trust prompt, no permission confirmations. This makes it ideal for automation.

Mode 2: Interactive PTY via tmux — Multi-Turn Sessions

Interactive mode gives you a full conversational REPL where you can send follow-up prompts, use slash commands, and watch Claude work in real time. Requires tmux orchestration.
When to use interactive mode:
  • Multi-turn iterative work (refactor → review → fix → test cycle)
  • Tasks requiring human-in-the-loop decisions
  • Exploratory coding sessions
  • When you need to use Claude’s slash commands (/compact, /review, /model)

PTY Dialog Handling (CRITICAL for Interactive Mode)

Claude Code presents up to two confirmation dialogs on first launch. You MUST handle these via tmux send-keys:

Dialog 1: Workspace Trust (first visit to a directory)

Handling: tmux send-keys -t <session> Enter — default selection is correct.

Dialog 2: Individual Permission Prompts (normal flow)

Each tool use that needs approval (file write, shell command, network) shows a prompt. Answer that one prompt — this is different from disabling prompts for the whole run:
Never send a blind Enter on a timer to approve prompts you have not read — that is the bypass flag with extra steps. A narrower opt-in than the full bypass is --permission-mode acceptEdits: file edits in the working directory are accepted, shell and other tool calls still prompt. Use it only in a dedicated worktree after reviewing the task.

Robust Dialog Handling Pattern

Note: After the first trust acceptance for a directory, the trust dialog won’t appear again.

Opt-in: —dangerously-skip-permissions (isolated environments only)

This disables permission prompts for the whole run — grants filesystem, shell, and network access with no prompts. Acceptable only in a throwaway worktree or isolated container.
To accept: tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter

CLI Subcommands

Structured JSON Output

Returns a JSON object with:
Key fields: session_id for resumption, num_turns for agentic loop count, total_cost_usd for spend tracking, subtype for success/error detection (success, error_max_turns, error_budget).

Streaming JSON Output

For real-time token streaming, use stream-json with --verbose:
Returns newline-delimited JSON events. Filter with jq for live text:
Stream events include system/api_retry with attempt, max_retries, and error fields (e.g., rate_limit, billing_error).

Bidirectional Streaming

For real-time input AND output streaming:
--replay-user-messages re-emits user messages on stdout for acknowledgment.

Piped Input

JSON Schema for Structured Extraction

Parse structured_output from the JSON result. Claude validates output against the schema before returning.

Session Continuation

Bare Mode for CI/Scripting

--bare skips hooks, plugins, MCP discovery, and CLAUDE.md loading. Fastest startup. Requires ANTHROPIC_API_KEY (skips OAuth). To selectively load context in bare mode:

Fallback Model for Overload

Automatically falls back to the specified model when the default is overloaded (print mode only).

Complete CLI Flags Reference

Session & Environment

Model & Performance

Permission & Safety

Output & Input Format

System Prompt & Context

Debugging

Agent Teams

Tool Name Syntax for —allowedTools / —disallowedTools

Settings & Configuration

Settings Hierarchy (highest to lowest priority)

  1. CLI flags — override everything
  2. Local project: .claude/settings.local.json (personal, gitignored)
  3. Project: .claude/settings.json (shared, git-tracked)
  4. User: ~/.claude/settings.json (global)

Permissions in Settings

Memory Files (CLAUDE.md) Hierarchy

  1. Global: ~/.claude/CLAUDE.md — applies to all projects
  2. Project: ./CLAUDE.md — project-specific context (git-tracked)
  3. Local: .claude/CLAUDE.local.md — personal project overrides (gitignored)
Use the # prefix in interactive mode to quickly add to memory: # Always use 2-space indentation.

Interactive Session: Slash Commands

Session & Context

Development & Review

Configuration & Tools

Custom Slash Commands

Create .claude/commands/<name>.md (project-shared) or ~/.claude/commands/<name>.md (personal):
Usage: /deploy production — $ARGUMENTS is replaced with the user’s input.

Skills (Natural Language Invocation)

Unlike slash commands (manually invoked), skills in .claude/skills/ are markdown guides that Claude invokes automatically via natural language when the task matches:

Interactive Session: Keyboard Shortcuts

General Controls

Mode Toggles

Multiline Input

Input Prefixes

Pro Tip: “ultrathink”

Use the keyword “ultrathink” in your prompt for maximum reasoning effort on a specific turn. This triggers the deepest thinking mode regardless of the current /effort setting.

PR Review Pattern

Quick Review (Print Mode)

Deep Review (Interactive + Worktree)

PR Review from Number

Claude Worktree with tmux

Creates an isolated git worktree at .claude/worktrees/feature-x AND a tmux session for it. Uses iTerm2 native panes when available; add --tmux=classic for traditional tmux.

Parallel Claude Instances

Run multiple independent Claude tasks simultaneously:

CLAUDE.md — Project Context File

Claude Code auto-loads CLAUDE.md from the project root. Use it to persist project context:
Be specific. Instead of “Write good code”, use “Use 2-space indentation for JS” or “Name test files with .test.ts suffix.” Specific instructions save correction cycles.

Rules Directory (Modular CLAUDE.md)

For projects with many rules, use the rules directory instead of one massive CLAUDE.md:
  • Project rules: .claude/rules/*.md — team-shared, git-tracked
  • User rules: ~/.claude/rules/*.md — personal, global
Each .md file in the rules directory is loaded as additional context. This is cleaner than cramming everything into a single CLAUDE.md.

Auto-Memory

Claude automatically stores learned project context in ~/.claude/projects/<project>/memory/.
  • Limit: 25KB or 200 lines per project
  • This is separate from CLAUDE.md — it’s Claude’s own notes about the project, accumulated across sessions

Custom Subagents

Define specialized agents in .claude/agents/ (project), ~/.claude/agents/ (personal), or via --agents CLI flag (session):

Agent Location Priority

  1. .claude/agents/ — project-level, team-shared
  2. --agents CLI flag — session-specific, dynamic
  3. ~/.claude/agents/ — user-level, personal

Creating an Agent

Invoke via: @security-reviewer review the auth module

Dynamic Agents via CLI

Claude can orchestrate multiple agents: “Use @db-expert to optimize queries, then @security to audit the changes.”

Hooks — Automation on Events

Configure in .claude/settings.json (project) or ~/.claude/settings.json (global):

All 8 Hook Types

Hook Environment Variables

Security Hook Examples

MCP Integration

Add external tool servers for databases, APIs, and services:

MCP Scopes

MCP in Print/CI Mode

--strict-mcp-config ignores all MCP servers except those from --mcp-config. Reference MCP resources in chat: @github:issue://123

MCP Limits & Tuning

  • Tool descriptions: 2KB cap per server for tool descriptions and server instructions
  • Result size: Default capped; use maxResultSizeChars annotation to allow up to 500K characters for large outputs
  • Output tokens: export MAX_MCP_OUTPUT_TOKENS=50000 — cap output from MCP servers to prevent context flooding
  • Transports: stdio (local process), http (remote), sse (server-sent events)

Monitoring Interactive Sessions

Reading the TUI Status

Look for these indicators:
  • ❯ at bottom = waiting for your input (Claude is done or asking a question)
  • ● lines = Claude is actively using tools (reading, writing, running commands)
  • ⏵⏵ bypass permissions on = status bar showing permissions mode
  • ◐ medium · /effort = current effort level in status bar
  • ctrl+o to expand = tool output was truncated (can be expanded interactively)

Context Window Health

Use /context in interactive mode to see a colored grid of context usage. Key thresholds:
  • < 70% — Normal operation, full precision
  • 70-85% — Precision starts dropping, consider /compact
  • > 85% — Hallucination risk spikes significantly, use /compact or /clear

Environment Variables

Cost & Performance Tips

  1. Use --max-turns in print mode to prevent runaway loops. Start with 5-10 for most tasks.
  2. Use --max-budget-usd for cost caps. Note: minimum ~$0.05 for system prompt cache creation.
  3. Use --effort low for simple tasks (faster, cheaper). high or max for complex reasoning.
  4. Use --bare for CI/scripting to skip plugin/hook discovery overhead.
  5. Use --allowedTools to restrict to only what’s needed (e.g., Read only for reviews).
  6. Use /compact in interactive sessions when context gets large.
  7. Pipe input instead of having Claude read files when you just need analysis of known content.
  8. Use --model haiku for simple tasks (cheaper) and --model opus for complex multi-step work.
  9. Use --fallback-model haiku in print mode to gracefully handle model overload.
  10. Start new sessions for distinct tasks — sessions last 5 hours; fresh context is more efficient.
  11. Use --no-session-persistence in CI to avoid accumulating saved sessions on disk.

Pitfalls & Gotchas

  1. Interactive mode REQUIRES tmux — Claude Code is a full TUI app. Using pty=true alone in Mibyan terminal works but tmux gives you capture-pane for monitoring and send-keys for input, which is essential for orchestration.
  2. The --dangerously-skip-permissions warning dialog defaults to “No, exit” — that default is the safe answer; only send Down then Enter when you deliberately opted into the bypass in an isolated environment. Print mode (-p) skips the dialog entirely.
  3. --max-budget-usd minimum is ~$0.05 — system prompt cache creation alone costs this much. Setting lower will error immediately.
  4. --max-turns is print-mode only — ignored in interactive sessions.
  5. Claude may use python instead of python — on systems without a python symlink, Claude’s bash commands will fail on first try but it self-corrects.
  6. Session resumption requires same directory — --continue finds the most recent session for the current working directory.
  7. --json-schema needs enough --max-turns — Claude must read files before producing structured output, which takes multiple turns.
  8. Trust dialog only appears once per directory — first-time only, then cached.
  9. Background tmux sessions persist — always clean up with tmux kill-session -t <name> when done.
  10. Slash commands (like /commit) only work in interactive mode — in -p mode, describe the task in natural language instead.
  11. --bare skips OAuth — requires ANTHROPIC_API_KEY env var or an apiKeyHelper in settings.
  12. Context degradation is real — AI output quality measurably degrades above 70% context window usage. Monitor with /context and proactively /compact.

Rules for Mibyans

  1. Prefer print mode (-p) for single tasks — cleaner, no dialog handling, structured output
  2. Use tmux for multi-turn interactive work — the only reliable way to orchestrate the TUI
  3. Always set workdir — keep Claude focused on the right project directory
  4. Set --max-turns in print mode — prevents infinite loops and runaway costs
  5. Monitor tmux sessions — use tmux capture-pane -t <session> -p -S -50 to check progress
  6. Look for the ❯ prompt — indicates Claude is waiting for input (done or asking a question)
  7. Clean up tmux sessions — kill them when done to avoid resource leaks
  8. Report results to user — after completion, summarize what Claude did and what changed
  9. Don’t kill slow sessions — Claude may be doing multi-step work; check progress instead
  10. Use --allowedTools — restrict capabilities to what the task actually needs