Koda Cowork User Manual

Local AI Collaboration Workspace —— Make Agent your reliable execution assistant (acting as secretary/colleague/expert), safely and efficiently completing tasks within project directories.

Why Choose Koda Cowork?

Essential Differences from General AI

Build Differentiated Agents

Koda Cowork 's core value lies in: Through Skills and MCP combination, build completely different specialized Agent.

Three Core Capabilities of Koda Cowork

1. Skills - Professional Capability Modules

Skills arecompressed packages of expert knowledge, each Skill is a set ofexpertiseand workflows.

• 9+ Built-in Skills: Data analysis, visualization, frontend design, document generation...
• Custom Skills: Use skill-creator to build your own professional capabilities
• Remote Installation: One-click install from GitHub repositories with audit pipeline
• Quality Assurance: skill-judge 8 Dimensionscoring, ensuring quality

2. MCP Plugins - External Connectors

MCP (Model Context Protocol) enables Agents to connect to any external service.

• 4 Built-in MCPs: Browser automation, web search, web scraping...
• Custom MCPs: Connect internal systems (CRM, ERP, databases)
• Flexible Configuration: Supports stdio, HTTP, SSE transport methods
• Environment Variables: Secure API key storage

3. Security Mechanisms - Controlled Execution

Local execution + Approval System, ensuring Agent behavior is controllable and traceable.

• Dangerous Operation Approval: Deleting, moving, overwriting files requires explicit approval
• Path Boundary Protection: Operations restricted to project directories only
• memory rules: Remember approval decisions to automate workflows
• Local First: All data stored locally, never uploaded to cloud

Vision and target

Application Scenarios

Core Features

Koda Cowork is a local collaboration application that transforms AI Agents into your assistants, safely executing tasks within your project directories. Each Workspace is independent, with its own conversation history, tool call records, and approval policies.

Key Features

Quick Start

1. Configure API Key

When launching Koda Cowork for the first time, you'll need to configure your Anthropic API Key:

1. Click the Settings icon ⚙️ in the top-right corner
2. Enter your API Key in the Anthropic tab
3. (Optional) Customize model name (default: claude-sonnet-4-20250514)
4. Click Save

2. Create Your First Workspace

1. Click the + New Workspace button in the left sidebar
2. Enter workspace name (e.g., "My Project")
3. Select the folder path to associate
4. Click Create

3. Send Your First Task

type your request in the chat input box, for example:

Help me analyze this project's structure, then tell me about its main features

The Agent will first generate a TODO plan, then begin execution after your confirmation.

Workspace types

Koda Cowork supports threeworkspace types to meet different scenario needs:

📁 Folder

Bound to a local folder, Agent can read, edit, and create files.
Use Cases: Code projects, document organization, batch file operations

💬 Chat

Conversation-only mode, not bound to any folder.
Use Cases: Consultation, discussion, creative brainstorming, code explanation

🤖 Sub-Agent

Configurable scheduled tasks that execute automatically on a schedule.
Use Cases: Regular reports, monitoring, automated tasks

Approval System

The security core of Koda Cowork — dangerous operations must receive your explicit approval before execution.

Operations Requiring Approval

• fs_rm - Delete files or folders
• fs_move - Move or rename files
• fs_write/fs_edit - Overwrite existing files

Approval Workflow

1. When Agent encounters a dangerous operation, an Approval Card pops up in the bottom-right corner
2. Card displays operationtype, targetpath, Risk Level
3. Select Allow or Reject
4. Optional: Check "Remember decision" to create a rule

memory rules

For frequent operations, you can creatememory rules, auto-handle next time:

• Scope: Global / Specific workspace
• Match conditions: ~300 name, path patterns
• Decision: Auto allow / Auto reject

Chat & Task Execution

Koda Cowork's chat interface is more than a conversation tool — it's a complete task execution environment.

Chat Interface Features

Smart Suggestions (Onboarding)

When entering a new workspace, Agent analyzes the folder structure and generates personalized task suggestions:

• AI Analysis: Automatically identifies project type (code/docs/data)
• Smart Suggestions: Generates recommended tasks based on project characteristics
• Quick Start: Click suggestions to execute directly
• Refreshable: Regenerate suggestions if not satisfied

Attachment System (Context Items)

Beyond chat content, you can provide files and folders as context for the Agent:

• 📎 Attachment Button: Click the paperclip icon left of the input box
• Files/Folders: Add local files or entire directories
• Context-Aware: Agent can read and analyze attachment content
• Count Indicator: Attachment button shows number of items added

Message Interactions

• Streaming Output: Real-time display of Agent's thinking and execution process
• Markdown Rendering: Supports code highlighting, tables, lists
• Message Actions: Copy message content, view timestamps
• History Summarization: Long conversations auto-compressed, keeping key info
• Quick ~30: One-click to top, previous question, latest message
• Unread Reminders: Shows new message count when away

Input Enhancements

• Multi-line Input: Shift + Enter for new line, Enter to send
• Auto Height: Input box adjusts automatically based on content
• Attachment Reminder: Send button shows number of attachments included
• State Disable: Input auto-disabled when Agent is working

Sending Tasks

Describe your needs in natural language in the chat input box:

Help me organize the Downloads folder - move images to Images, documents to Documents

Agent will first analyze the task, then generate a TODO plan list for your confirmation.

TODO Plan System

Plan Generation

After receiving a task, Agent generates a structured TODO plan:

• Title: Concise task description
• Status: pending / in_progress / completed
• Assignee: Usually "Koda" (Agent name)
• Editable: User can modify plan content

Plan Confirmation

Before Agent starts execution, you can:

• View Plan: Understand Agent's execution approach
• Adjust Plan: Add, delete, modify tasks
• Confirm Execution: Agent starts working after approval
• Cancel Execution: Stop if you change your mind

Execution Monitoring

After confirming the plan, Agent begins execution. The right task panel shows real-time updates:

TODO Panel

• Statuschanges: Tasks move from pending → in_progress → completed
• Progress Tracking: Currently executing task
• Work Time: Shows how long Agent has been working
• Task Statistics: Count of completed/failed/waiting

Execution Logs

• ~300 Calls: Name, parameters, execution time of each tool
• Execution Results: Success/failure/needs approval
• Detailed Output: Expand to view complete tool returns
• Timestamps: Precise time of each operation

Streaming Output

During execution, Agent outputs in real-time:

• Thinking ~200: Shows Agent's decision logic
• Execution Progress: What's currently being done
• Result Explanation: Summary after operation completes
• Markdown Format: Supports rich text and code blocks

TaskStatus

Agent has three mainStatus:

Efficient Task Description Tips

Good Task Descriptions

• Be Specific: Specify files, folders, operationtype
• Include Context: Explain it's needed, what the expected result is
• Break Down: Complex tasks can be split into multiple steps
• Provide Examples: If specific format is needed, giveProvide Examples

Provide ExamplesComparison

Collaboration Modes

Break Downexecution

ComplexTaskcanBreak Downcompleted:

1. Phase 1: "First analyze the project structure, tell me your understanding"
2. After confirming understanding: "Based on your understanding, refactor module X"
3. Check results: "Look at code quality, any improvements needed?"

Iterative Optimization

After Agent completes execution, you can:

• Request Retry: "That step failed, please retry"
• Provide Feedback: "This approach isn't quite right, I need..."
• Continue Deepening: "On this basis, optimize further"

File Preview

Koda Cowork powerful built-in file Previewsystem supporting multiple formats, no need to open external applications.

Supported filetype

Preview Operations

• Double-click File: Opens in preview window
• Top ~300bar: Show in Finder / Open with default app
• HTML Special Handling: Uses standalone runtime window, ensures relative path resources load correctly

Skills System

Skills are Koda Cowork's extension mechanism, each Skill is a set ofexpertiseand workflows, that enable Agents with domain capabilities.

Built-in Skills

Koda Cowork includes 9+ built-in professional Skills:

Creating Custom Skills

Koda Cowork provides a complete Skill creation toolkit, making it easy to extend Agent capabilities.

Skill Structure

Each Skill contains the following:

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description)
│   └── Markdown guide
└── optional resources
    ├── scripts/       # canexecution scripts
    ├── references/    # references
    └── assets/        # templates, icons and other resources

Creation ~200 (6 Steps)

1. Understand Requirements: Use specific examples to clarify what problem the Skill solves
2. Plan Content: Determine what scripts, references, assets are needed
3. Initialize Skill: Use Cowork to auto-generate template
4. Edit Content: Implement SKILL.md and related resources
5. Package and Publish: Generate .skill file for use
6. Iterative Optimization: Improve based on actual usage

Creating Skills in Koda Cowork

Cowork includes two built-in Skills: skill-creator and skill-judge:

Using skill-creator to Create Skills

In any workspace, tell the Agent:

I want to create a [your Skill domain] Skill, help me plan it

The Agent will guide you through:

• Analyze specific use cases
• Plan Skill structure (scripts/references/assets)
• Write SKILL.md frontmatter and content
• Test and package

Core Skill Design Principles

1. Frontmatter (Trigger Mechanism)

The YAML metadata at the beginning of SKILL.md is the key to Skill activation:

---
name: my-skill
description: "Concise description of skill functionality and trigger scenarios. Includes: 
- WHAT: what it does
- WHEN: When to use
- KEYWORDS: Trigger keywords
Example: Handle PDF document creation, editing, analysis. 
Use when user mentions PDF, document processing, or needs to work with .pdf files. 
---

description is the most important field —— Agent onlyBased on description decide whether to activate Skill.

2. Progressive Disclosure

Organize content in three layers to save token:

• Layer 1 (metadata): name + description, always in memory
• Layer 2 (SKILL.md): Coreguide, ideally < 500 lines
• Layer 3 (resources): scripts/references/assets, on-demandload

3. Appropriate Freedom

Choose guidance granularity based on task fragility:

• highfreedom (text guidance): creativeTask, design (frontend-design)
• in etc.freedom (pseudocode): havePatterncan be followed but there ischangesroom for
• lowfreedom (precisescripts): error-prone operations, formatprocessing (docx/pdf)

4. Anti-Pattern List

Half of expert knowledge is "what not to do". Clearly list NEVER items:

NEVER use generic AI aesthetics:
- Overused fonts: Inter, Roboto, Arial
- Purple gradients on white
- Cookie-cutter layouts

Skill Quality Assessment

use skill-judge evaluate your Skill quality:

Please evaluate the quality of the my-skill I just created

skill-judge scores across 8 Dimensionmakepoints (max 120 points):

Skill Storagelocation

Created Skills should be placed in:

• user Skills: ~/.koda-cowork/skills/
• appBuilt-in Skills: apps/cowork/skills/

Installing Skills from Remote Sources

Cowork withfrom Git Repository or Local DirectoryRemote Installation Skills, and giveCompleteAudit Pipelineensuringsecurity.

Installation Methods

https://github.com/user/skills-repo

/path/to/skills

.claude-plugin/marketplace.json

Audit Pipeline (4 steps)

Cowork giveenterprise-grade Skill audit workflow, ensuringInstall of Skills securitycanrely on:

Risk Assessment

Static check automatically evaluates Skill risk level:

Using the Audit Pipeline

Install remote Skills through Cowork's UI:

1. Open Settings
   • Click the ⚙️ settings icon in the top-right
   • Switch to the "Skills" tab
   • Click the "Audit & Install" button
2. Enter Source
   • Git URL: https://github.com/anthropics/skills
   • Local path: /Users/xxx/my-skills
   • Click "Select Directory" button to browse folders
3. Wait for Audit
   • Auto-execute 4-step audit process
   • vieweach Skill of Risk Levelandscoring
   • Read LLM-generated strengths / issues / recommendations
4. Select and Install
   • Check Skills to install
   • Click "Install" button
   • Skills are copied to ~/.koda-cowork/skills/

Manual Installation (Skip Audit)

For trusted sources, you can manually copy Skill files:

# 1. Clone repository
git clone https://github.com/user/skills-repo.git /tmp/skills

# 2. Copy to user directory
cp -r /tmp/skills/my-skill ~/.koda-cowork/skills/

# 3. Restart Cowork or wait for auto-reload

Claude Marketplace Format

If the repository contains .claude-plugin/marketplace.json, Cowork automatically displays Skills grouped by plugin.

marketplace.json Provide Examples:

{
  "name": "My Skills Collection",
  "description": "Commonly used Skills in the organization",
  "skills": [
    {
      "name": "my-skill-1",
      "description": "First skill"
    },
    {
      "name": "my-skill-2",
      "description": "Second skill"
    }
  ]
}

Common Skill Creation Patterns

Based onTasktypeselectappropriate designPattern:

MCP Plugin System

Cowork supports the Model Context Protocol (MCP) plugin system, extending Agent capabilities through external services. MCP servers can provide additional tools, data sources, and integrations.

Built-in MCP Servers

Cowork comes pre-configured with the following MCP servers:

MCP Configuration Files

MCP configuration is stored in the ~/.koda-cowork/mcp/ directory:

• mcp_settings.json: mainconfigurationfile (built-inServerDefaultconfiguration)
• mcp_settings.d/*.json: user-definedServer
• .env: API keyandEnvironment Variables

Configuration Format

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    },
    "http-server": {
      "transport": "streamableHttp",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MY_TOKEN}"
      }
    }
  }
}

transporttype

Environment Variablesconfiguration

Sensitive information like API keys is stored in ~/.koda-cowork/mcp/.env:

# Cowork MCP secrets
# Zhipu / Z.ai
Z_AI_API_KEY=your_api_key_here
Z_AI_MODE=ZHIPU

# Other services
MY_API_KEY=another_key_here

Variable Placeholders

in mcp_settings.json in ${VARIABLE_NAME} referenceEnvironment Variables:

{
  "mcpServers": {
    "glm-zai-mcp-server": {
      "env": {
        "Z_AI_API_KEY": "${Z_AI_API_KEY}",
        "Z_AI_MODE": "${Z_AI_MODE}"
      }
    }
  }
}

management MCP Server

Via Settings Interface

1. Open Settings → MCP tab
2. viewallhavealreadyconfiguration of Serverand itsStatus
3. Enable/DisablespecificServer (Workspace-Level Override)
4. click"import"addnewServer
5. click"..."menuviewdetails ordeleteServer

manualaddServer

Create JSON file in ~/.koda-cowork/mcp/mcp_settings.d/ directory:

# 1. Create configuration file
cat > ~/.koda-cowork/mcp/mcp_settings.d/my-server.json << 'EOF'
{
  "mcpServers": {
    "my-custom-server": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}
EOF

# 2. Add key to .env
echo "MY_API_KEY=xxx" >> ~/.koda-cowork/mcp/.env

# 3. Restart Cowork or wait for auto-reload

MCP ServerStatus

Workspace-Level Override

youcanfor specific workspaceEnable or Disable MCP Server:

• Default: Follow global settings
• Enable: force in this workspaceEnablethe Server
• Disable: force in this workspaceDisablethe Server

This is useful when configuring different tool sets for different workspaces.

Debugging MCP Issues

FAQ

• Servercannot start: Check if command path is correct, dependencies installed
• Authentication failed: Verify API key in .env is correct
• Connection timeout: HTTP Servercheck url andnetworkconnection
• Variable not replaced: Verify placeholder format is ${VARIABLE_NAME}

viewServerdetails

insettings → MCP inclickServername, canview:

• Complete configuration (command/args/env/url/headers)
• List of provided tools
• Error messages (IfFailed to start)
• Source (built-in/user-defined)

Advanced Features

History Archive

export workspace of conversation historyand~300 Callsrecords, for backup or analysis. with JSON and Markdown Format.

debugPattern

Developerscanopen debug drawer, viewraw event streams, Agent Statusandsystem logs.

MCP Plugins

Supports Model Context Protocol (MCP) plugin system to extend Agent capabilities. MCP Configuration Fileslocated at ~/.koda-cowork/mcp/.

FAQ

Q: Where is Cowork's data stored?

All data (settings, workspaces, conversation history) is stored locally in the cowork/ folder under the system userData directory. Never uploaded to any cloud.

Q: Can I run multiple workspaces simultaneously?

Yes. Each workspace has its own Agent instance and can be active simultaneously. However, it's recommended to focus on one task at a time to avoid confusion.

Q: What if Agent execution fails?

viewright sideExecution Logs, understand the failurereason. Then tell Agent "That step failed, please retry" or givemore contexthelpit correct.

Q: how toCustom Skills？

Skills are standard SKILL.md files. Create your skill folder in the ~/.koda-cowork/skills/ directory, including SKILL.md andrelatedresourcesis ready. referenceBuilt-in Skills of structure.

Q: Which LLM models are supported?

Current version only supports Anthropic Claude series (claude-sonnet-4-20250514, etc.). Future plans include expanding to other models.