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
claudeonce to log in (browser OAuth for Pro/Max, or setANTHROPIC_API_KEY) - Console auth:
claude auth login --consolefor API key billing - SSO auth:
claude auth login --ssofor Enterprise - Check status:
claude auth status(JSON) orclaude auth status --text(human-readable) - Health check:
claude doctor— checks auto-updater and installation health - Version check:
claude --version(requires v2.x+) - Update:
claude updateorclaude 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.
- 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
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.- 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)
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: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
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.tmux send-keys -t <session> Down && sleep 0.3 && tmux send-keys -t <session> Enter
CLI Subcommands
Print Mode Deep Dive
Structured JSON Output
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, usestream-json with --verbose:
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
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
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)
- CLI flags — override everything
- Local project:
.claude/settings.local.json(personal, gitignored) - Project:
.claude/settings.json(shared, git-tracked) - User:
~/.claude/settings.json(global)
Permissions in Settings
Memory Files (CLAUDE.md) Hierarchy
- Global:
~/.claude/CLAUDE.md— applies to all projects - Project:
./CLAUDE.md— project-specific context (git-tracked) - Local:
.claude/CLAUDE.local.md— personal project overrides (gitignored)
# 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):
/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
.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-loadsCLAUDE.md from the project root. Use it to persist project context:
.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
.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
.claude/agents/— project-level, team-shared--agentsCLI flag — session-specific, dynamic~/.claude/agents/— user-level, personal
Creating an Agent
@security-reviewer review the auth module
Dynamic Agents via CLI
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
maxResultSizeCharsannotation 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
❯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 barctrl+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
/compactor/clear
Environment Variables
Cost & Performance Tips
- Use
--max-turnsin print mode to prevent runaway loops. Start with 5-10 for most tasks. - Use
--max-budget-usdfor cost caps. Note: minimum ~$0.05 for system prompt cache creation. - Use
--effort lowfor simple tasks (faster, cheaper).highormaxfor complex reasoning. - Use
--barefor CI/scripting to skip plugin/hook discovery overhead. - Use
--allowedToolsto restrict to only what’s needed (e.g.,Readonly for reviews). - Use
/compactin interactive sessions when context gets large. - Pipe input instead of having Claude read files when you just need analysis of known content.
- Use
--model haikufor simple tasks (cheaper) and--model opusfor complex multi-step work. - Use
--fallback-model haikuin print mode to gracefully handle model overload. - Start new sessions for distinct tasks — sessions last 5 hours; fresh context is more efficient.
- Use
--no-session-persistencein CI to avoid accumulating saved sessions on disk.
Pitfalls & Gotchas
- Interactive mode REQUIRES tmux — Claude Code is a full TUI app. Using
pty=truealone in Mibyan terminal works but tmux gives youcapture-panefor monitoring andsend-keysfor input, which is essential for orchestration. - The
--dangerously-skip-permissionswarning 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. --max-budget-usdminimum is ~$0.05 — system prompt cache creation alone costs this much. Setting lower will error immediately.--max-turnsis print-mode only — ignored in interactive sessions.- Claude may use
pythoninstead ofpython— on systems without apythonsymlink, Claude’s bash commands will fail on first try but it self-corrects. - Session resumption requires same directory —
--continuefinds the most recent session for the current working directory. --json-schemaneeds enough--max-turns— Claude must read files before producing structured output, which takes multiple turns.- Trust dialog only appears once per directory — first-time only, then cached.
- Background tmux sessions persist — always clean up with
tmux kill-session -t <name>when done. - Slash commands (like
/commit) only work in interactive mode — in-pmode, describe the task in natural language instead. --bareskips OAuth — requiresANTHROPIC_API_KEYenv var or anapiKeyHelperin settings.- Context degradation is real — AI output quality measurably degrades above 70% context window usage. Monitor with
/contextand proactively/compact.
Rules for Mibyans
- Prefer print mode (
-p) for single tasks — cleaner, no dialog handling, structured output - Use tmux for multi-turn interactive work — the only reliable way to orchestrate the TUI
- Always set
workdir— keep Claude focused on the right project directory - Set
--max-turnsin print mode — prevents infinite loops and runaway costs - Monitor tmux sessions — use
tmux capture-pane -t <session> -p -S -50to check progress - Look for the
❯prompt — indicates Claude is waiting for input (done or asking a question) - Clean up tmux sessions — kill them when done to avoid resource leaks
- Report results to user — after completion, summarize what Claude did and what changed
- Don’t kill slow sessions — Claude may be doing multi-step work; check progress instead
- Use
--allowedTools— restrict capabilities to what the task actually needs

