illusion-usage

name	illusion-usage
description	Dual-purpose guide for agents. Scenario A — agent autonomously drives Illusion Code via non-interactive print mode (-p). Scenario B — agent helps its human master install and use Illusion Code's interactive TUI/Web modes. Invoke when an agent needs to operate Illusion Code, install it for a user, or teach a user how to use it.

Illusion Code Usage: Agent Dual-Role Guide

This skill serves two scenarios. Detect your role first, then follow the matching track.

Live documentation: ALWAYS fetch the latest docs from GitHub before acting — do not rely on hardcoded commands in this skill. Repo: https://github.com/YunTaiHua/illusion-code. Docs: https://github.com/YunTaiHua/illusion-code/tree/main/docs. Use WebFetch, web_fetch, or an equivalent tool to read the URLs in Reference URLs below.

Role Detection

Your situation	Track to follow
You (the agent) will invoke illusion -p as a subprocess to do coding tasks autonomously	Track A: Agent-Driven Print Mode
Your human master wants to install/use Illusion Code themselves, and you guide them	Track B: Human-Friendly TUI & Web
Both — you'll drive it AND teach your master	Read both tracks; Track A for your own use, Track B for your master

---

Track A: Agent-Driven Print Mode

Use print mode when YOU (the agent) operate Illusion Code as a non-interactive subprocess. Every -p invocation is an atomic request-response — no waiting for interactive input within the same turn.

A.0 Fetch Current Docs (MANDATORY before install)

Use a web fetch tool to read these in order. This skill only outlines the workflow — concrete flags, file paths, and auth providers may have changed.

1. README — https://github.com/YunTaiHua/illusion-code
2. Getting Started — https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/getting-started.md
3. Commands — https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/commands.md
4. Settings — https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/settings.md

If any URL 404s, fall back to PyPI (https://pypi.org/project/illusion-code/) and follow its homepage link. Do NOT assume commands below are current — verify against fetched docs.

A.1 Installation

Recommended (no Node.js required):

pip install illusion-code
illusion --version

From source (developers, requires Node.js 18+):

git clone https://github.com/YunTaiHua/illusion-code.git
cd illusion-code
pip install .          # or: pip install -e .   (editable)

Always confirm the exact install command from the fetched Getting Started doc.

A.2 Authentication (Interactive, One-Time)

Print mode requires prior auth. This is the one interactive step — complete it once via TTY before any -p invocation:

illusion auth login

Common providers (verify against fetched Settings doc):

• Custom — API format (anthropic/openai), base URL, API key, model name
• Anthropic — direct API key
• OpenAI — direct API key
• GitHub Copilot — OAuth device flow
• OpenAI Codex — OAuth device flow

Credentials stored in ~/.illusion/credentials.json, grouped by env_N. Models are referenced as env_N.model_N (e.g., env_1.model_2).

A.3 Verify Environment

illusion -p "Reply with: OK" --output-format json

Should print {"type": "result", "text": "OK"} and exit 0. If non-zero, check credentials/settings files.

A.4 Print Mode Core

illusion -p "<prompt>"

Critical: -p's value must be the last argument (typer parses it greedily).

Exit codes (always check)

Code	Meaning	Action
0	Normal completion	Parse stdout for result
1	Error	Read stderr; fix and retry
2	Waiting for user input (question, plan approval, or permission approval)	Answer with illusion -c -p "<answer>" (answer for question, "approve" for plan, "Y"/"F"/"N" for permission)

stdout vs stderr

• stdout: assistant text, JSON results
• stderr: status, permission denials, questions, errors

For programmatic parsing, use --output-format json (single object at end) or --output-format stream-json (one object per line, events: assistant_delta, tool_started, tool_completed, assistant_complete, error, status, system).

A.5 Permission Modes (Critical)

Print mode uses cross-turn Y/F/N callback for permissions. Choose explicitly:

Mode	Behavior	Use when
default (omit)	Mutating tools trigger cross-turn Y/F/N approval	Selective approval, interactive-ish
full_auto	All tools execute	Autonomous coding, writes, commands
plan	All mutation tools blocked	Planning only

Plan Approval Flow:

• Terminal/Web: Approval card UI shown inline
• Print mode: Cross-turn (exit code 2, resume with illusion -c -p "approve")
• Channel: Plan content sent as message, user replies to approve/reject

default mode: Cross-Turn Permission Approval (Y/F/N)

In default mode, mutating tools trigger a cross-turn approval instead of direct denial:

1. Turn 1: illusion -p "write a file" → exit 2, stderr shows Permission request: {tool}. Use Y/F/N...
2. Turn 2: illusion -c -p "Y" → approve once; "F" → always allow (persists to .illusion/permissions.json); "N" → deny

# Read-only (no permission needed)
illusion -p "Analyze the project structure"

# Autonomous coding (skip Y/F/N approval)
illusion --permission-mode full_auto -p "Fix the failing tests"

# default mode with Y/F/N approval
illusion -p "Write a test file"
# → exit 2, stderr shows permission request with Y/F/N guidance
illusion -c -p "Y"   # allow once
illusion -c -p "F"   # always allow (persists)
illusion -c -p "N"   # deny

Autonomous agents: default to full_auto for coding tasks to avoid Y/F/N interruptions.

A.6 ask_user_question — Cross-Turn Non-Interactive

When the LLM calls ask_user_question, print mode persists the question and exits with code 2. Answer in the next invocation:

# Turn 1
illusion -p "Refactor auth.py"
# → exit 2, stderr prints questions with [header] markers

# Turn 2
illusion -c -p "<answer>"

Answer formats

Scenario	Format	Example
Single question	Plain text	strawberry
Single (multiSelect)	Comma-separated	strawberry,mango
Multiple questions	JSON, keys = headers	{"Fruit": "strawberry", "OS": "Windows"}
Multiple (multiSelect)	JSON arrays	{"Fruit": ["strawberry", "mango"]}

Headers shown in brackets in Turn 1 stderr (e.g., [Fruit] Which fruit?). Non-JSON input is passed as-is (backward compatible).

Shell escaping for JSON

illusion -c -p "{\"Fruit\": \"strawberry\", \"OS\": \"Windows\"}"

If your agent passes args as a list (not shell string), no escaping needed.

Detecting pending questions

1. Exit code 2 → question pending
2. Parse stderr for [<header>] lines
3. Build JSON answer from headers
4. Resume with illusion -c -p "<json>"

A.7 Session Continuity

Flag	Description
-c / --continue	Continue most recent session in cwd
-r <ID> / --resume <ID>	Resume specific session by ID

Both require -p. Use -c for linear flows; -r <ID> for parallel sessions. Session files under ~/.illusion/sessions/ (verify path in docs).

A.8 Persistent Parameters

Set once, survive across sessions:

Flag	Description
-m <env_N.model_N> / --model	Model selection
-e <LEVEL> / --effort	Effort: low/medium/high/max
-t <N> / --max-turns	Max agentic turns
--permission-mode <MODE>	Permission mode

Non-persistent: -c, -r, -n, --output-format, --dangerously-skip-permissions (avoid this — prefer --permission-mode full_auto).

A.9 Common Agent Workflows

Read-only analysis

illusion -p "Find all TODO comments" --output-format json

Autonomous bug fix

illusion --permission-mode full_auto -p "Fix test_login_expires in tests/test_auth.py"

Multi-turn clarification

illusion -p "Add a rate limiter to the API"
# exit 2 → [Algorithm] [Limit]
illusion -c -p "{\"Algorithm\": \"token bucket\", \"Limit\": \"100\"}"

Parallel sessions

illusion -p "Refactor db layer" -n "db"
illusion -p "Add telemetry" -n "tel"
illusion -r <session-id> -p "Continue"

A.10 Agent Integration Checklist

1. Installed — illusion --version works
2. Authenticated — illusion auth login done via TTY
3. Verified — trivial -p "OK" exits 0
4. Docs fetched — read latest Getting Started, Commands, Settings
5. Permission strategy — full_auto for coding, default for read-only
6. Exit code handling — wrapper checks 0/1/2
7. JSON answer builder — ready for exit 2 cases
8. Session tracking — capture/reuse session IDs

---

Track B: Human-Friendly TUI & Web

Use this track when your human master wants to install and use Illusion Code themselves. Default to interactive modes (TUI/Web) — they are far more user-friendly than print mode for humans. Guide your master step by step, and fetch the latest docs to give accurate instructions.

B.0 Fetch Current Docs (MANDATORY before guiding)

Use WebFetch / web_fetch to read the latest docs before giving any instruction. Repo: https://github.com/YunTaiHua/illusion-code.

Recommended fetch order for guiding humans:

1. README — https://github.com/YunTaiHua/illusion-code — show your master the project overview and latest features
2. Getting Started — https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/getting-started.md (or docs/zh-CN/getting-started.md for Chinese) — install steps, first-run guide
3. Commands — https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/commands.md (or docs/zh-CN/commands.md) — slash commands for interactive sessions
4. Settings — https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/settings.md — for advanced configuration

Match the doc language to your master's preference. Both en/ and zh-CN/ directories exist in the docs.

B.1 Guide Your Master Through Installation

Recommended for most users (no Node.js required):

Tell your master to run in their terminal:

pip install illusion-code

Then verify:

illusion --version

Always confirm the exact install command from the fetched Getting Started doc — the project may have added new install methods (e.g., uv, pipx, homebrew).

For developers (requires Node.js 18+):

git clone https://github.com/YunTaiHua/illusion-code.git
cd illusion-code
pip install -e .

B.2 Guide Authentication (Interactive)

Tell your master this is a one-time setup:

illusion auth login

This launches an interactive provider picker. Walk them through the options:

• Custom — for self-hosted or third-party API-compatible endpoints
• Anthropic — direct Claude API key
• OpenAI — direct OpenAI API key
• GitHub Copilot — OAuth device flow (no API key needed, just sign in to GitHub)
• OpenAI Codex — OAuth device flow

Verify the provider list from the fetched Settings doc. Read the auth section carefully and relay the exact prompts your master will see.

B.3 Recommend Interactive Modes (Default for Humans)

Terminal TUI (Recommended primary mode)

illusion

This launches the React-based terminal interface — full-screen, mouse support, streaming responses, slash commands, todo panel, etc. This is what most humans should use.

Fetch the Commands doc to learn the available slash commands (/help, /clear, /model, /config, /permissions, etc.) so you can teach your master.

Web UI (Supplementary, browser-based)

illusion web
# or with custom port
illusion web --port 8080

Opens a browser-based interface. Good when:

• A terminal is unavailable (remote server, tablet with web browser)
• User prefers mouse-driven UI
• Sharing a session on a screen

The Web UI is supplementary — the terminal TUI is the primary recommended mode. Confirm this from the fetched Getting Started doc.

When to mention print mode to humans

Only mention illusion -p to humans for:

• One-off quick questions from scripts
• CI/automation pipelines
• Piping output to other tools

For everyday coding, steer them to illusion (TUI).

B.4 Teach Basic Interactive Usage

Walk your master through their first session:

# Start
illusion

# In the session, try:
# - Type a question and press Enter
# - Type /help to see slash commands
# - Type /model to switch models
# - Type /clear to start fresh
# - Press Ctrl+C twice or /exit to quit

Fetch the Commands doc to give them an accurate list of slash commands and keyboard shortcuts.

B.5 Guide Configuration (Optional, Advanced)

If your master wants to customize, point them to ~/.illusion/settings.json:

• Model: -m env_1.model_2 or /model in session
• Effort: -e high or /thinking in session
• Permission mode: --permission-mode full_auto or /permissions in session
• Hooks: automate actions after tool use (see Settings doc)
• MCP servers: connect external tools (see Settings doc)
• Plugins: extend functionality (see Settings doc)

Fetch the Settings doc to give accurate JSON schema examples. Never hardcode config snippets from this skill — always relay the latest from the docs.

B.6 Guide Channel Setup (Optional, Mobile Access)

If your master wants to use Illusion Code from their phone via messaging apps:

• Feishu/Lark — illusion channel login, select Feishu
• WeChat — illusion channel login, select WeChat (iLink Bot API)
• QQ — illusion channel login, select QQ (official Bot API)

Fetch the Channels doc for setup details: https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/channels.md (or docs/zh-CN/channels.md).

B.7 Human-Facing Anti-Patterns

• Don't tell humans to use illusion -p for everyday coding — steer them to illusion (TUI)
• Don't hardcode install steps — fetch the latest Getting Started doc
• Don't skip authentication — illusion auth login is required before first use
• Don't recommend --dangerously-skip-permissions — use /permissions in session or --permission-mode full_auto
• Don't assume the Web UI replaces the TUI — TUI is primary, Web is supplementary
• Don't give config examples from memory — fetch the Settings doc for current schema

B.8 Human Integration Checklist

Before your master starts coding:

1. Installed — illusion --version works
2. Authenticated — illusion auth login completed
3. Knows how to start — illusion launches the TUI
4. Knows slash commands — at least /help, /clear, /model, /exit
5. Knows permission modes — /permissions to switch
6. Knows where docs live — bookmark the repo and docs directory
7. Optional: Web UI — illusion web for browser access
8. Optional: Channels — mobile access via Feishu/WeChat/QQ

---

Reference URLs (verify they resolve before relying on them)

• Repository: https://github.com/YunTaiHua/illusion-code
• PyPI package: https://pypi.org/project/illusion-code/
• Getting Started (EN): https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/getting-started.md
• Getting Started (中文): https://github.com/YunTaiHua/illusion-code/blob/main/docs/zh-CN/getting-started.md
• Commands (EN): https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/commands.md
• Commands (中文): https://github.com/YunTaiHua/illusion-code/blob/main/docs/zh-CN/commands.md
• Settings (EN): https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/settings.md
• Settings (中文): https://github.com/YunTaiHua/illusion-code/blob/main/docs/zh-CN/settings.md
• Channels (EN): https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/channels.md
• Channels (中文): https://github.com/YunTaiHua/illusion-code/blob/main/docs/zh-CN/channels.md
• Architecture (EN): https://github.com/YunTaiHua/illusion-code/blob/main/docs/en/architecture.md

If any URL above 404s, the docs may have been reorganized — start from https://github.com/YunTaiHua/illusion-code and navigate to the docs/ directory to find the current paths.