Qoder Agent

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

🧠 Model Selection

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

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

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

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:

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

⚠️ 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

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