Qoder Agent (Print Mode - Non-Interactive)

Use Print mode (-p) for all Qoder CLI work in OpenClaw. TUI mode is not supported in automated environments.

✅ All-Sessions Ready: This skill works in:

• Direct 1:1 chats
• Group chats (DingTalk, Discord, Slack, etc.)
• Shared workspace sessions
• Private sessions

---

⚠️ Important: Print Mode Only

TUI mode is NOT supported in OpenClaw or other automated environments due to TTY requirements.

Always use Print mode with the -p flag:

# ✅ Correct - Print mode (non-interactive)
bash workdir:~/project command:"qodercli -p 'Add error handling'"

# ❌ Wrong - TUI mode requires interactive terminal
bash pty:true command:"qodercli"  # Will fail

---

🔐 Environment Setup (Auto-Detected)

Qoder CLI authentication is automatically available via:

# Environment variable (set in ~/.zshrc)
QODER_PERSONAL_ACCESS_TOKEN="your_token_here"

# Or check if already authenticated
qodercli status

In any session type, the environment variable is inherited from the shell, so Qoder CLI works seamlessly.

---

🚀 Quick Start

Basic Usage

# Quick one-shot task
bash workdir:~/project command:"qodercli -p 'Add error handling to the API calls'"

# With ultimate model for best quality
bash workdir:~/project command:"qodercli --model=ultimate -p 'Refactor this module'"

# With JSON output
bash workdir:~/project command:"qodercli --output-format=json -p 'Analyze this code'"

# Continue last session
bash workdir:~/project command:"qodercli -c -p 'Continue the refactoring'"

# Max turns limit
bash workdir:~/project command:"qodercli --max-turns=10 -p 'Fix the bug'"

# Yolo mode (skip permissions)
bash workdir:~/project command:"qodercli --yolo -p 'Make the changes'"

---

🎯 Print Mode Flags

Flag	Description	Example
-p	Required - Run non-interactively	qodercli -p "task"
-q	Quiet mode (hide spinner)	qodercli -q -p "task"
--output-format	Output format: text, json, stream-json	qodercli --output-format=json
-w	Specify workspace directory	qodercli -w /path/to/project
-c	Continue last session	qodercli -c -p "continue"
-r	Resume specific session	qodercli -r <session-id>
--model	Model tier selection	qodercli --model=ultimate
--max-turns	Maximum dialog turns (0 = unlimited)	qodercli --max-turns=10
--max-output-tokens	Max tokens: 16k, 32k	qodercli --max-output-tokens=32k
--yolo	Skip permission checks	qodercli --yolo
--allowed-tools	Allow only specified tools	qodercli --allowed-tools=READ,WRITE
--disallowed-tools	Disallow specified tools	qodercli --disallowed-tools=Bash
--agents	JSON object defining custom agents	qodercli --agents='{"reviewer":{...}}'
--attachment	Attach image files (repeatable)	qodercli --attachment=img.png

---

🧠 Model Selection

Qoder CLI uses automatic model routing - it selects the globally optimal model based on task characteristics. You can override this:

Model Value	Use Case	Speed	Quality	Cost
auto	Default - automatic routing	⚡⚡⚡	⭐⭐⭐	💰💰💰
efficient	Quick tasks, simple queries	⚡⚡⚡⚡	⭐⭐	💰💰
lite	Very simple tasks	⚡⚡⚡⚡⚡	⭐	💰
performance	Complex tasks needing depth	⚡⚡	⭐⭐⭐⭐	💰💰💰💰
ultimate	Best quality - refactoring, architecture, code review	⚡	⭐⭐⭐⭐⭐	💰💰💰💰💰
qmodel	Qwen model family	⚡⚡⚡	⭐⭐⭐⭐	💰💰💰
q35model	Qwen 3.5 specific	⚡⚡⚡	⭐⭐⭐⭐	💰💰💰
mmodel	MiniMax model	⚡⚡⚡	⭐⭐⭐⭐	💰💰💰
gmodel	GPT model family	⚡⚡	⭐⭐⭐⭐⭐	💰💰💰💰

Recommendations:

• Default: Use --model=auto (let Qoder choose)
• Refactoring/Architecture: --model=ultimate
• Quick fixes: --model=efficient
• Code review: --model=performance or ultimate
• Simple queries: --model=lite or efficient

---

🎯 Quest Mode (Spec-Driven Development)

Quest Mode allows you to write specifications while AI automatically completes development tasks using subagents.

# Quest mode via prompt
bash workdir:~/project command:"qodercli --model=ultimate -p 'Build a REST API with authentication, rate limiting, and logging'"

Quest Mode automatically:

1. Analyzes requirements
2. Routes to appropriate subagents
3. Coordinates multi-step development
4. Ensures consistency across files

---

🤖 Subagents

Subagents are specialized AI agents for specific tasks with their own context windows and tool permissions.

Create a Subagent (Manual)

Create markdown files in:

• ~/.qoder/agents/<agentName>.md - User-level (all projects)
• ${project}/agents/<agentName>.md - Project-level

Example: code-review agent

---
name: code-review
description: Code review expert for quality and security checks
tools: Read, Grep, Glob, Bash
---

You are a senior code reviewer responsible for ensuring code quality.

Checklist:
1. Readability and code style
2. Naming conventions
3. Error handling
4. Security checks
5. Test coverage
6. Performance considerations

Use Subagents

# Explicit invocation
bash workdir:~/project command:"qodercli -p 'Use code-review subagent to check code issues'"

# Implicit invocation
bash workdir:~/project command:"qodercli -p 'Analyze this code for potential performance issues'"

# Chained subagents
bash workdir:~/project command:"qodercli -p 'First use design subagent for system design, then use code-review subagent'"

# Custom agents inline
bash workdir:~/project command:"qodercli --agents='{\"reviewer\":{\"description\":\"Reviews code\",\"prompt\":\"You are a code reviewer\"}}' -p 'Review this'"

---

🌳 Worktree (Parallel Jobs)

Worktree jobs are concurrent jobs that use Git worktrees to run tasks in parallel, avoiding read/write conflicts.

Requirements: Git installed and usable locally.

Commands

Command	Description
qodercli --worktree "job description"	Create and start new worktree job
qodercli jobs --worktree	List existing worktree jobs
qodercli rm <jobId>	Remove a job (delete worktree)

Create a Job

# Basic worktree job (non-interactive)
bash workdir:~/project command:"qodercli --worktree -p 'Fix issue #78'"

# With branch specification
bash workdir:~/project command:"qodercli --worktree --branch=main -p 'Implement feature'"

# With max turns
bash workdir:~/project command:"qodercli --worktree --max-turns=20 -p 'Complex refactoring'"

View Jobs

bash workdir:~/project command:"qodercli jobs --worktree"

Delete Jobs

bash workdir:~/project command:"qodercli rm <jobId>"

⚠️ Warning: Deletion is irreversible. Proceed with caution.

Parallel Issue Fixing Example

# Multiple worktrees for parallel work
bash workdir:~/project background:true command:"qodercli --worktree -p 'Fix issue #78'"
bash workdir:~/project background:true command:"qodercli --worktree -p 'Fix issue #99'"

# Monitor progress
process action:list
process action:log sessionId:XXX

---

🔌 MCP Servers

Qoder CLI integrates with any standard MCP (Model Context Protocol) tool.

Add MCP Servers

# Basic syntax
bash command:"qodercli mcp add <name> -- <command>"

# Example: Playwright for browser control
bash command:"qodercli mcp add playwright -- npx -y @playwright/mcp@latest"

Recommended MCP Tools

# Context7 - Upstash context management
bash command:"qodercli mcp add context7 -- npx -y @upstash/context7-mcp@latest"

# DeepWiki - Wikipedia/knowledge access
bash command:"qodercli mcp add deepwiki -- npx -y mcp-deepwiki@latest"

# Chrome DevTools - Browser automation
bash command:"qodercli mcp add chrome-devtools -- npx chrome-devtools-mcp@latest"

Manage MCP Servers

# List servers
bash command:"qodercli mcp list"

# Remove server
bash command:"qodercli mcp remove playwright"

---

🔐 Permissions

Qoder CLI enforces precise tool execution permissions.

Configuration Files (precedence: high → low)

1. ${project}/.qoder/settings.local.json - Project-level, highest (gitignore)
2. ${project}/.qoder/settings.json - Project-level
3. ~/.qoder/settings.json - User-level

Permission Strategies

Strategy	Description
allow	Automatically allow matching operations
deny	Automatically deny matching operations
ask	Prompt for permission (default for outside project)

Example Configuration

{
  "permissions": {
    "ask": [
      "Read(!/Users/demo/projects/myproject/**)",
      "Edit(!/Users/demo/projects/myproject/**)"
    ],
    "allow": [
      "Read(/Users/demo/projects/myproject/**)",
      "Edit(/Users/demo/projects/myproject/**)"
    ],
    "deny": [
      "Bash(rm -rf /**)"
    ]
  }
}

Permission Types

1. Read & Edit Rules

Patterns follow gitignore-style matching:

Pattern Form	Description	Example	Matches
/path	Absolute from system root	Read(/Users/demo/**)	/Users/demo/xx
~/path	From home directory	Read(~/Documents/*.png)	/Users/demo/Documents/xx.png
path or ./path	Relative to current dir	Read(/*.java)	./xx.java
!**	Negation pattern	Read(!**/node_modules/**)	Excludes node_modules

2. WebFetch Rules

Restrict domains for network fetch:

{
  "permissions": {
    "allow": [
      "WebFetch(domain:example.com)",
      "WebFetch(domain:*.github.io)"
    ]
  }
}

3. Bash Rules

Restrict commands for shell execution:

{
  "permissions": {
    "allow": [
      "Bash(npm run build)",
      "Bash(npm run test:*)",
      "Bash(curl http://site.com/:*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(sudo *)"
    ]
  }
}

---

📝 Memory (AGENTS.md)

Qoder CLI uses AGENTS.md as memory - content is auto-loaded as context.

File Locations

• User-level: ~/.qoder/AGENTS.md - Applies to all projects
• Project-level: ${project}/AGENTS.md - Applies to current project

Typical Content

• Development standards and notes
• Overall system architecture
• Project-specific conventions
• API documentation
• Testing requirements

Generate/Manage

# Manually create AGENTS.md in project root
cat > ~/project/AGENTS.md << 'EOF'
# Project Guidelines

## Architecture
- MVC pattern
- REST API design

## Code Style
- ESLint strict mode
- Prettier formatting
EOF

---

⚡ Advanced Options

Option	Description	Example
-w	Specify workspace directory	qodercli -w /path/to/project
-c	Continue last session	qodercli -c -p "continue"
-r	Resume specific session	qodercli -r <session-id>
--allowed-tools	Allow only specified tools	qodercli --allowed-tools=READ,WRITE
--disallowed-tools	Disallow specified tools	qodercli --disallowed-tools=Bash
--max-turns	Maximum dialog turns	qodercli --max-turns=10
--yolo	Skip permission checks	qodercli --yolo
--worktree	Create worktree job	qodercli --worktree "task"
--branch	Set branch for worktree	qodercli --worktree --branch=main
--agents	Define custom agents inline	qodercli --agents='{...}'
--attachment	Attach image files	qodercli --attachment=img.png

---

⚠️ Rules

1. Print mode only - TUI mode not supported in OpenClaw
2. Always use -p flag - Non-interactive mode required
3. Respect workdir - Qoder sees only the specified directory's context
4. Monitor with process:log - check background session progress
5. Use worktrees for parallel work - avoid read/write conflicts
6. Initialize AGENTS.md - helps Qoder understand project context
7. Configure permissions - set appropriate access rules per project
8. Leverage subagents - specialized agents for specific tasks
9. Add MCP servers - extend capabilities with external tools
10. Works in all sessions - environment variables are inherited automatically
11. Use ultimate model for complex tasks - refactoring, architecture, code review

---

Progress Updates (Critical)

When you spawn Qoder CLI in the background, keep the user in the loop:

• Send 1 short message when you start (what's running + where)
• Then only update again when something changes:
  • a milestone completes (build finished, tests passed)
  • the CLI asks a question / needs input
  • you hit an error or need user action
  • the CLI finishes (include what changed + where)
• If you kill a session, immediately say you killed it and why

This prevents the user from seeing only "Agent failed before reply" and having no idea what happened.

---

Auto-Notify on Completion

For long-running background tasks, append a wake trigger:

bash workdir:~/project background:true command:"qodercli --model=ultimate 'Build a REST API for todos.

When completely finished, run: openclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"

This triggers an immediate wake event — you get pinged in seconds, not minutes.

---

🌐 Cross-Session Usage

In Group Chats (DingTalk, Discord, Slack)

# Just use normal commands - environment is inherited
bash workdir:~/project command:"qodercli -p 'Help me fix this bug'"

# No special setup needed!

In Direct Messages

Same as group chats - works out of the box.

In Shared Workspaces

# Specify the workspace explicitly
bash workdir:/shared/project command:"qodercli --model=ultimate -p 'Refactor this'"

Privacy Note

• Qoder CLI only accesses the specified workdir
• Environment variables are inherited from the host shell
• No credentials are exposed in chat messages
• Each session has isolated Qoder CLI state

---

📊 Comparison with Other Coding Agents

Feature	Qoder CLI	Codex	Claude Code
Print Mode	✅	✅	❌
Subagents	✅	❌	❌
Worktrees	✅	❌	❌
MCP Servers	✅	✅	✅
Memory (AGENTS.md)	✅	✅	✅
Model Selection	✅ (auto-routing)	❌	❌
Quest Mode	✅	❌	❌
Permission System	✅ (granular)	⚠️	⚠️
All-Sessions Ready	✅	⚠️	⚠️

Qoder CLI strengths:

• Subagents for specialized tasks
• Worktrees for parallel development
• Quest mode for spec-driven development
• Automatic model routing
• Granular permission system
• Cross-session compatibility

---

📋 Quick Reference Card

# Quick task (print mode, auto model)
qodercli -p "Your prompt"

# High-quality task (ultimate model)
qodercli --model=ultimate -p "Your prompt"

# Quest mode (spec-driven)
qodercli -p "Build a REST API with auth"

# Background task (worktree)
qodercli --worktree -p "Your task"

# Check status
qodercli status

# Skip permissions (use with caution)
qodercli --yolo -p "Your prompt"

# Continue last session
qodercli -c -p "Continue"

# JSON output
qodercli --output-format=json -p "Analyze"

# With custom subagents
qodercli --agents='{"reviewer":{...}}' -p "Review this"

---

🔧 Troubleshooting

Not Logged In

# Check status
qodercli status

# Set environment variable
export QODER_PERSONAL_ACCESS_TOKEN="your_token"

Permission Denied

# Use yolo mode (caution)
qodercli --yolo -p "task"

# Or configure permissions in ~/.qoder/settings.json

Model Selection Issues

# Explicitly specify model
qodercli --model=ultimate -p "task"

# Or use auto for automatic routing
qodercli --model=auto -p "task"

TUI Mode Error

TUI mode is NOT supported in OpenClaw. Always use Print mode:

# ✅ Correct
qodercli -p "Your task"

# ❌ Wrong (will fail)
qodercli  # TUI requires interactive terminal