### Copy Example Configuration File

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Copy the example nanobot configuration file to start customizing your settings.

```bash
cp nanobot_config.json.example nanobot_config.json
```

--------------------------------

### Start Frontend Development Server

Source: https://github.com/hkuds/deepcode/blob/main/new_ui/README.md

Installs frontend dependencies and starts the Vite development server. Run this command in the frontend directory.

```bash
cd new_ui/frontend
npm install  # First time only
npm run dev
```

--------------------------------

### Start Backend Development Server

Source: https://github.com/hkuds/deepcode/blob/main/new_ui/README.md

Installs backend dependencies and starts the FastAPI development server. Run this command in the backend directory.

```bash
cd new_ui/backend
pip install -r requirements.txt  # First time only
uvicorn main:app --reload --port 8000
```

--------------------------------

### Configuration File Example

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/summarize/SKILL.md

An example of the optional configuration file `~/.summarize/config.json` to set a default model.

```json
{
  "model": "openai/gpt-5.2"
}
```

--------------------------------

### Install nanobot with uv

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Install a stable and fast version of nanobot using the uv package installer.

```bash
uv tool install nanobot-ai
```

--------------------------------

### Install nanobot from Source

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Install the latest features of nanobot directly from its GitHub repository. This is recommended for development purposes.

```bash
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .
```

--------------------------------

### Development Installation with UV

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Sets up a development environment using UV for Python dependency management and installs frontend dependencies.

```bash
git clone https://github.com/HKUDS/DeepCode.git
cd DeepCode/

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python=3.13
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

# Install frontend dependencies
npm install --prefix new_ui/frontend
```

--------------------------------

### Install nanobot from PyPI

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Install the latest stable release of nanobot from the Python Package Index (PyPI).

```bash
pip install nanobot-ai
```

--------------------------------

### Start Development Server

Source: https://github.com/hkuds/deepcode/blob/main/new_ui/README.md

Executes the development startup script for both backend and frontend. Ensure the script has execute permissions.

```bash
cd new_ui
chmod +x scripts/start_dev.sh
./scripts/start_dev.sh
```

--------------------------------

### Start vLLM Server

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Use this command to start a vLLM server with a specified model. Ensure the port is accessible.

```bash
vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
```

--------------------------------

### Install Node.js on Ubuntu/Debian

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Installs Node.js on Ubuntu or Debian systems using NodeSource repository.

```bash
# Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
```

--------------------------------

### Development Installation with pip

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Sets up a development environment using traditional pip for Python dependencies and installs frontend dependencies.

```bash
git clone https://github.com/HKUDS/DeepCode.git
cd DeepCode/

pip install -r requirements.txt

# Install frontend dependencies
npm install --prefix new_ui/frontend
```

--------------------------------

### Install Node.js on macOS

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Installs Node.js using Homebrew on macOS.

```bash
# macOS (using Homebrew)
brew install node
```

--------------------------------

### Basic Summarization Examples

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/summarize/SKILL.md

Demonstrates how to use the summarize command for URLs, local files, and YouTube links. Ensure the appropriate model is specified.

```bash
summarize "https://example.com" --model google/gemini-3-flash-preview
```

```bash
summarize "/path/to/file.pdf" --model google/gemini-3-flash-preview
```

```bash
summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto
```

--------------------------------

### Direct Installation of DeepCode

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Installs the DeepCode package directly using pip and downloads the configuration template.

```bash
# 🚀 Install DeepCode package directly
pip install deepcode-hku

# 🔑 Download the unified configuration template
curl -O https://raw.githubusercontent.com/HKUDS/DeepCode/main/deepcode_config.json.example
cp deepcode_config.json.example deepcode_config.json
```

--------------------------------

### Bundled Scripts Directory Example

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/skill-creator/SKILL.md

Example of a directory structure for bundled executable scripts within a skill.

```tree
scripts/ - Executable code (Python/Bash/etc.)
```

--------------------------------

### Bundled Assets Directory Example

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/skill-creator/SKILL.md

Example of a directory structure for bundled assets (files used in output) within a skill.

```tree
assets/ - Files used in output (templates, icons, fonts, etc.)
```

--------------------------------

### Bundled References Directory Example

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/skill-creator/SKILL.md

Example of a directory structure for bundled reference documentation within a skill.

```tree
references/ - Documentation intended to be loaded into context as needed
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/skill-creator/SKILL.md

Example of the required YAML frontmatter for a SKILL.md file, specifying the skill's name and description.

```yaml
name: skill-name
description: Skill description
```

--------------------------------

### Check Prerequisites Versions

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Verify that your Python, Node.js, and npm installations meet the minimum version requirements.

```bash
# Check your versions
python --version   # Should be 3.9+
node --version     # Should be 18+
npm --version      # Should be 8+
```

--------------------------------

### Run Nanobot Gateway

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Start the nanobot gateway service to enable chat channel integrations.

```bash
nanobot gateway
```

--------------------------------

### Heartbeat Task Format Example

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/workspace/AGENTS.md

This is an example of how tasks should be formatted within the HEARTBEAT.md file for periodic execution.

```markdown
- [ ] Check calendar and remind of upcoming events
- [ ] Scan inbox for urgent emails
- [ ] Check weather forecast for today
```

--------------------------------

### Initialize a New Skill

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/skill-creator/SKILL.md

Use the init_skill.py script to create a new skill template. Specify the skill name, output path, and optionally include resource directories or example files.

```bash
scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
```

```bash
scripts/init_skill.py my-skill --path skills/public
```

```bash
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
```

```bash
scripts/init_skill.py my-skill --path skills/public --resources scripts --examples
```

--------------------------------

### Install Frontend Packages with Prefix

Source: https://github.com/hkuds/deepcode/blob/main/README.md

When encountering 'Could not read package.json' errors during 'npm install', ensure you are in the correct directory or use the --prefix flag to specify the frontend directory.

```bash
npm install --prefix new_ui/frontend
```

--------------------------------

### DeepCode CLI Interactive Input Examples

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Examples of commands to use within the DeepCode CLI's main menu prompt for session management and file processing. Supports resuming sessions, creating new ones, and processing files directly.

```text
/resume                 # pick a previous session from a numbered list
/new My experiment      # create and switch to a fresh session
/session                # show the currently active session
@/absolute/path.pdf     # process a file without opening the file picker
@"C:\path with spaces\paper.pdf"
@https://arxiv.org/pdf/....

```

--------------------------------

### SKILL.md Structure Example

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/skill-creator/SKILL.md

Illustrates the required structure of a SKILL.md file, including YAML frontmatter and Markdown body.

```markdown
---
name: skill-name
description: Skill description
---

# Skill Title

Skill instructions and guidance go here.
```

--------------------------------

### Editable Install for Development

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Installs the project in editable mode, allowing the global 'deepcode' command to launch the current source checkout. Changes are reflected immediately.

```bash
pip install -e .
```

--------------------------------

### Launch DeepCode with Docker

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Recommended method for running DeepCode. Clones the repository, copies configuration, and starts the Docker container. Access the application at http://localhost:8000.

```bash
git clone https://github.com/HKUDS/DeepCode.git
cd DeepCode/
cp deepcode_config.json.example \
   deepcode_config.json
# Edit deepcode_config.json with your API keys

./deepcode_docker/run_docker.sh
# Access → http://localhost:8000
```

--------------------------------

### Launch DeepCode and Nanobot Services

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Start both DeepCode and nanobot services in the background using the provided script. This command checks Docker, validates configurations, and builds images if necessary.

```bash
./nanobot/run_nanobot.sh -d          # Start both DeepCode + nanobot in background
```

--------------------------------

### Nanobot Management Commands

Source: https://github.com/hkuds/deepcode/blob/main/README.md

A list of commands to manage the nanobot service, including starting, stopping, restarting, building, viewing logs, checking status, and cleaning up containers and images.

```bash
./nanobot/run_nanobot.sh              # Start (foreground)
./nanobot/run_nanobot.sh -d           # Start (background)
./nanobot/run_nanobot.sh stop         # Stop all services
./nanobot/run_nanobot.sh restart      # Restart (config changes take effect immediately)
./nanobot/run_nanobot.sh --build      # Force rebuild Docker images
./nanobot/run_nanobot.sh logs         # View real-time logs
./nanobot/run_nanobot.sh status       # Health check
./nanobot/run_nanobot.sh clean        # Remove containers & images
```

--------------------------------

### Configure MCP Filesystem Server for Windows

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Manually configure the MCP filesystem server for Windows users. This involves installing the server globally and specifying its command and arguments.

```bash
# 1. Install MCP servers globally
npm i -g @modelcontextprotocol/server-filesystem

# 2. Find your global node_modules path
npm -g root
```

```json
{
  "tools": {
    "mcpServers": {
      "filesystem": {
        "type": "stdio",
        "command": "node",
        "args": ["C:/Program Files/nodejs/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js", "."]
      }
    }
  }
}
```

--------------------------------

### Manage DeepCode with Docker Compose

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Commands for building, starting, stopping, and viewing logs of the DeepCode application using Docker Compose.

```bash
docker compose -f deepcode_docker/docker-compose.yml up --build   # Build & start
docker compose -f deepcode_docker/docker-compose.yml down         # Stop
docker compose -f deepcode_docker/docker-compose.yml logs -f      # Logs
```

--------------------------------

### Get Weather Forecast (Open-Meteo)

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/weather/SKILL.md

Fetches current weather data in JSON format from Open-Meteo using latitude and longitude. Suitable for programmatic use.

```bash
curl -s "https://api.open-meteo.com/v1/forecast?latitude=51.5&longitude=-0.12&current_weather=true"
```

--------------------------------

### Get Detailed Weather (wttr.in)

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/weather/SKILL.md

Fetches detailed weather information including temperature, humidity, and wind using wttr.in. Requires `curl`.

```bash
curl -s "wttr.in/London?format=%l:+%c+%t+%h+%w"
# Output: London: ⛅️ +8°C 71% ↙5km/h
```

--------------------------------

### Troubleshooting Language Output

Source: https://github.com/hkuds/deepcode/blob/main/README.md

If the bot is producing output in the wrong language, consider switching the model. For example, 'minimax-m2.1' defaults to Chinese, while Claude or GPT models are better for English.

--------------------------------

### Start Isolated Tmux Session

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/tmux/SKILL.md

Creates a new detached tmux session with a specific name and launches a Python REPL within the first pane. Captures recent pane output.

```bash
SOCKET_DIR="${NANOBOT_TMUX_SOCKET_DIR:-"${TMPDIR:-/tmp}/nanobot-tmux-sockets"}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/nanobot.sock"
SESSION=nanobot-python

tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
```

--------------------------------

### Upgrade Nanobot for Security Patches

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/SECURITY.md

Regularly check for and apply Nanobot updates to incorporate the latest security fixes. This is crucial for maintaining a secure installation.

```bash
# Check for updates weekly
pip install --upgrade nanobot-ai
```

--------------------------------

### Get Specific Fields from a Pull Request via API

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/github/SKILL.md

Use the `gh api` command for advanced queries. This example retrieves the title, state, and login of the user for a specific pull request, filtering with `--jq`.

```bash
gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
```

--------------------------------

### Build and Run Nanobot with Docker

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Instructions for building the Nanobot Docker image, initializing configuration, running the gateway, and executing single commands.

```bash
# Build the image
docker build -t nanobot .

```

```bash
# Initialize config (first time only)
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard

```

```bash
# Edit config on host to add API keys
vim ~/.nanobot/config.json

```

```bash
# Run gateway (connects to Telegram/WhatsApp)
docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway

```

```bash
# Or run a single command
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot agent -m "Hello!"

```

```bash
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot status

```

--------------------------------

### Initialize nanobot

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Run the onboard command to initialize nanobot. Ensure your API keys are set up.

```bash
nanobot onboard
```

--------------------------------

### Get Full Forecast (wttr.in)

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/weather/SKILL.md

Retrieves the full weather forecast for a location from wttr.in. Requires `curl`.

```bash
curl -s "wttr.in/London?T"
```

--------------------------------

### Get Current Weather (wttr.in)

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/weather/SKILL.md

Fetches current weather for a location using wttr.in with a simple format. Requires `curl`.

```bash
curl -s "wttr.in/London?format=3"
# Output: London: ⛅️ +8°C
```

--------------------------------

### Build Production Application

Source: https://github.com/hkuds/deepcode/blob/main/new_ui/README.md

Executes the production build script for the entire application. Ensure the script has execute permissions.

```bash
cd new_ui
chmod +x scripts/build.sh
./scripts/build.sh
```

--------------------------------

### YouTube Transcript Extraction

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/summarize/SKILL.md

Use the `--extract-only` flag with YouTube URLs to get a best-effort transcript. This is useful when a full transcript is needed.

```bash
summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto --extract-only
```

--------------------------------

### Reinstall Frontend Node Modules

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Resolve issues with a blank frontend page by navigating to the frontend directory and reinstalling node modules after removing the existing ones.

```bash
cd new_ui/frontend && rm -rf node_modules && npm install
```

--------------------------------

### Launch DeepCode Locally (No Docker)

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Runs the DeepCode frontend and backend directly on the host machine. Useful when Docker is unavailable or for iterating on local source changes. Access the frontend at http://localhost:5173 and the backend at http://localhost:8000.

```bash
deepcode --local
# Frontend → http://localhost:5173
# Backend  → http://localhost:8000
# Ctrl+C to stop
```

--------------------------------

### Configure LLM Provider API Keys

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Set up API keys for different LLM providers like OpenAI, Anthropic, and Gemini. Environment variables can be used for sensitive keys.

```json
{
  "providers": {
    "openai":    { "apiKey": "your_openai_api_key" },
    "anthropic": { "apiKey": "${ANTHROPIC_API_KEY}" },
    "gemini":    { "apiKey": "" }
  }
}
```

--------------------------------

### Run Nanobot as a Dedicated User

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/SECURITY.md

Execute Nanobot using a dedicated user account with limited privileges. Avoid running Nanobot as root.

```bash
sudo useradd -m -s /bin/bash nanobot
sudo -u nanobot nanobot gateway
```

--------------------------------

### Configure Nanobot for Local vLLM

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

This JSON configuration enables the vLLM provider and sets a default model for agents. The apiKey can be any non-empty string for local servers.

```json
{
  "providers": {
    "vllm": {
      "apiKey": "dummy",
      "apiBase": "http://localhost:8000/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "meta-llama/Llama-3.1-8B-Instruct"
    }
  }
}
```

--------------------------------

### Launch DeepCode via Scripts (macOS/Linux/Windows)

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Alternative methods to launch DeepCode using shell scripts or Python. Supports local execution and classic Streamlit UI.

```bash
# macOS / Linux
./run.sh
# or: python deepcode.py --local

# Windows
run.bat
# or: python deepcode.py --local

# Classic Streamlit UI
deepcode --classic

# CLI mode
deepcode --cli
# or: python cli/main_cli.py
```

--------------------------------

### Chat with nanobot Agent

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Interact with the nanobot agent by running the agent command with a query. This demonstrates a basic chat interaction.

```bash
nanobot agent -m "What is 2+2?"
```

--------------------------------

### Wait for Text in Tmux Pane

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/tmux/SKILL.md

Example usage of a helper script to poll a tmux pane for a specific pattern with configurable options for target, pattern type, timeout, interval, and history lines.

```bash
{baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern' [-F] [-T 20] [-i 0.5] [-l 2000]
```

--------------------------------

### Configure Default Web Search Server

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Set the default MCP server for web search. The 'filesystem' server is used by default for reading local files.

```json
{
  "tools": { "defaultSearchServer": "filesystem" }
}
```

--------------------------------

### Project Structure Overview

Source: https://github.com/hkuds/deepcode/blob/main/new_ui/README.md

Illustrates the directory layout for the DeepCode New UI project, separating backend, frontend, and scripts.

```tree
new_ui/
├── backend/                    # FastAPI Backend
│   ├── main.py                # Entry point
│   ├── config.py              # Configuration
│   ├── api/
│   │   ├── routes/            # REST API endpoints
│   │   └── websockets/        # WebSocket handlers
│   ├── services/              # Business logic
│   └── models/                # Pydantic models
│
├── frontend/                   # React Frontend
│   ├── src/
│   │   ├── components/        # React components
│   │   ├── pages/             # Page components
│   │   ├── hooks/             # Custom hooks
│   │   ├── stores/            # Zustand stores
│   │   ├── services/          # API client
│   │   └── types/             # TypeScript types
│   ├── package.json
│   └── vite.config.ts
│
└── scripts/
    ├── start_dev.sh           # Development startup
    └── build.sh               # Production build
```

--------------------------------

### Enable/Disable Plugins using Registry

Source: https://github.com/hkuds/deepcode/blob/main/workflows/plugins/USAGE.md

Manage plugin activation and deactivation using the default registry. Use `disable` to turn off a plugin and `enable` to activate one by its name.

```python
from workflows.plugins import get_default_registry

registry = get_default_registry()

# 禁用需求分析插件
registry.disable("requirement_analysis")

# 启用计划确认插件
registry.enable("plan_review")
```

--------------------------------

### Set Secure File Permissions

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/SECURITY.md

Apply strict file permissions (700 for directories, 600 for files) to sensitive Nanobot configuration and authentication files.

```bash
chmod 700 ~/.nanobot
chmod 600 ~/.nanobot/config.json
chmod 700 ~/.nanobot/whatsapp-auth
```

--------------------------------

### Chat with Local LLM

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Initiate a chat with your configured local LLM using the nanobot agent command.

```bash
nanobot agent -m "Hello from my local LLM!"
```

--------------------------------

### Save Weather Forecast as PNG (wttr.in)

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/weather/SKILL.md

Downloads a weather forecast as a PNG image to a specified file path. Requires `curl`.

```bash
curl -s "wttr.in/Berlin.png" -o /tmp/weather.png
```

--------------------------------

### Skill Directory Structure

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/skill-creator/SKILL.md

Shows the typical directory structure for a skill, including the required SKILL.md and optional bundled resources.

```tree
skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter metadata (required)
│   │   ├── name: (required)
│   │   └── description: (required)
│   └── Markdown instructions (required)
└── Bundled Resources (optional)
    ├── scripts/          - Executable code (Python/Bash/etc.)
    ├── references/       - Documentation intended to be loaded into context as needed
    └── assets/           - Files used in output (templates, icons, fonts, etc.)
```

--------------------------------

### Troubleshooting Configuration Changes

Source: https://github.com/hkuds/deepcode/blob/main/README.md

If configuration changes are not taking effect, simply restart the nanobot service. A full rebuild of Docker images is not necessary for configuration updates.

```bash
./nanobot/run_nanobot.sh restart
```

--------------------------------

### Configure nanobot with OpenRouter API Key

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Configure nanobot to use the OpenRouter API by setting your API key in the `~/.nanobot/config.json` file. This is recommended for global users. You can also specify a default model.

```json
{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-xxx"
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-opus-4-5"
    }
  }
}
```

--------------------------------

### Package Skill Script

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/skill-creator/SKILL.md

Use this script to package your skill into a distributable .skill file. It automatically validates the skill before packaging.

```bash
scripts/package_skill.py <path/to/skill-folder>
```

```bash
scripts/package_skill.py <path/to/skill-folder> ./dist
```

--------------------------------

### Search for Access Denied Logs

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/SECURITY.md

Use this command to search Nanobot's log file for 'Access denied' entries, which can indicate unauthorized access attempts.

```bash
grep "Access denied" ~/.nanobot/logs/nanobot.log
```

--------------------------------

### Nanobot Project Structure

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

An overview of the Nanobot project's directory layout, detailing the purpose of each main folder.

```tree
nanobot/
├── agent/          # 🧠 Core agent logic
│   ├── loop.py     #    Agent loop (LLM ↔ tool execution)
│   ├── context.py  #    Prompt builder
│   ├── memory.py   #    Persistent memory
│   ├── skills.py   #    Skills loader
│   ├── subagent.py #    Background task execution
│   └── tools/      #    Built-in tools (incl. spawn)
├── skills/         # 🎯 Bundled skills (github, weather, tmux...)
├── channels/       # 📱 WhatsApp integration
├── bus/            # 🚌 Message routing
├── cron/           # ⏰ Scheduled tasks
├── heartbeat/      # 💓 Proactive wake-up
├── providers/      # 🤖 LLM providers (OpenRouter, etc.)
├── session/        # 💬 Conversation sessions
├── config/         # ⚙️ Configuration
└── cli/            # 🖥️ Commands

```

--------------------------------

### Configure Nanobot for WhatsApp

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Enable the WhatsApp channel integration. Replace the placeholder phone number with your actual number.

```json
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890"]
    }
  }
}
```

--------------------------------

### Configure OpenAI-Compatible Providers

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Use OpenAI-compatible providers by overriding the apiBase and specifying model slugs. This allows integration with services like OpenRouter.

```json
{
  "agents": {
    "defaults": {
      "provider": "openrouter",
      "model": "z-ai/glm-5.1"
    },
    "planning":       { "provider": "openrouter", "model": "z-ai/glm-5.1" },
    "implementation": { "provider": "openrouter", "model": "z-ai/glm-5.1" }
  },
  "providers": {
    "openai":     { "apiKey": "your_openai_api_key" },
    "openrouter": { "apiKey": "your_openrouter_key", "apiBase": "https://openrouter.ai/api/v1" }
  }
}
```

--------------------------------

### Configure Nanobot for Telegram

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Enable and configure the Telegram channel integration. Replace YOUR_BOT_TOKEN and YOUR_USER_ID with your actual credentials.

```json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}
```

--------------------------------

### Add New Provider Specification

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Define a new provider by adding a ProviderSpec to the registry. This includes its name, keywords for model matching, environment variable key, display name, and LiteLLM prefixing behavior.

```python
ProviderSpec(
    name="myprovider",                   # config field name
    keywords=("myprovider", "mymodel"),  # model-name keywords for auto-matching
    env_key="MYPROVIDER_API_KEY",        # env var for LiteLLM
    display_name="My Provider",          # shown in `nanobot status`
    litellm_prefix="myprovider",         # auto-prefix: model → myprovider/model
    skip_prefixes=("myprovider/",)      # don't double-prefix
)
```

--------------------------------

### View a Workflow Run

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/github/SKILL.md

View details of a specific workflow run using its ID. This command can help identify which steps failed. Use `--repo owner/repo` to specify the repository.

```bash
gh run view <run-id> --repo owner/repo
```

--------------------------------

### Monitor Nanobot Logs

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/SECURITY.md

Enable and monitor Nanobot's log files for security events and unusual activity. Ensure log files are secured.

```bash
# Configure log monitoring
tail -f ~/.nanobot/logs/nanobot.log
```

--------------------------------

### Login WhatsApp Channel

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Initiate the WhatsApp channel login process. This requires Node.js version 18 or higher. Scan the QR code with your WhatsApp application.

```bash
nanobot channels login
```

--------------------------------

### Add Dynamic Task with Cron

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/cron/SKILL.md

Schedules a task for the agent to execute at a specified interval. The `message` parameter should describe the task. The agent will perform the task and report the result.

```python
cron(action="add", message="Check HKUDS/nanobot GitHub stars and report", every_seconds=600)
```

--------------------------------

### Check for Vulnerable Dependencies (Node.js)

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/SECURITY.md

Navigate to the 'bridge' directory and use 'npm audit' to check for vulnerable Node.js dependencies. Use 'npm audit fix' to resolve them.

```bash
cd bridge
npm audit
npm audit fix
```

--------------------------------

### Write File Content

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/workspace/TOOLS.md

Writes content to a file, creating parent directories if they do not exist. Be cautious with overwriting existing files.

```python
write_file(path: str, content: str) -> str
```

--------------------------------

### Create and Register a Custom Interaction Plugin

Source: https://github.com/hkuds/deepcode/blob/main/workflows/plugins/USAGE.md

Define a custom plugin by inheriting from `InteractionPlugin` and implementing methods like `should_trigger`, `create_interaction`, and `process_response`. Register the custom plugin with the registry to make it available for use in workflows.

```python
from workflows.plugins import InteractionPlugin, InteractionPoint, InteractionRequest

class MyCustomPlugin(InteractionPlugin):
    name = "my_custom_plugin"
    description = "My custom interaction"
    hook_point = InteractionPoint.BEFORE_IMPLEMENTATION
    priority = 50

    async def should_trigger(self, context):
        return context.get("enable_my_plugin", True)

    async def create_interaction(self, context):
        return InteractionRequest(
            interaction_type="custom_interaction",
            title="Custom Check",
            description="Please confirm...",
            data={"key": "value"},
            options={"yes": "Confirm", "no": "Cancel"},
        )

    async def process_response(self, response, context):
        if response.action == "yes":
            context["custom_confirmed"] = True
        else:
            context["workflow_cancelled"] = True
        return context

# 注册插件
registry.register(MyCustomPlugin())
```

--------------------------------

### Slack Channel Configuration

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Configure nanobot to use Slack via Socket Mode. Requires Bot Token and App-Level Token. Socket Mode avoids the need for a public URL.

```json
{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-வுகளை",
      "appToken": "xapp-வுகளை",
      "groupPolicy": "mention"
    }
  }
}
```

--------------------------------

### List Directory Contents

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/workspace/TOOLS.md

Lists the contents of a specified directory. The output is a string representation of the directory's contents.

```python
list_dir(path: str) -> str
```

--------------------------------

### Background Tasks

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/workspace/TOOLS.md

Spawn subagents to handle tasks in the background.

```APIDOC
## spawn

### Description
Spawn a subagent to handle a task in the background.

### Signature
```python
spawn(task: str, label: str = None) -> str
```

### Usage
Use for complex or time-consuming tasks that can run independently. The subagent will complete the task and report back when done.
```

--------------------------------

### Cron Time Expressions

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/cron/SKILL.md

Illustrates how to use different time expressions for scheduling. `every_seconds` is used for fixed intervals, while `cron_expr` allows for more complex cron-like scheduling.

```python
cron(action="add", message="", every_seconds=1200)
```

```python
cron(action="add", message="", every_seconds=3600)
```

```python
cron(action="add", message="", cron_expr="0 8 * * *")
```

```python
cron(action="add", message="", cron_expr="0 17 * * 1-5")
```

--------------------------------

### Add New Provider Configuration Field

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Extend the ProvidersConfig model to include a configuration field for the new provider. This allows Nanobot to manage settings for the added provider.

```python
class ProvidersConfig(BaseModel):
    ...
    myprovider: ProviderConfig = ProviderConfig()
```

--------------------------------

### View Logs for Failed Steps in a Workflow Run

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/nanobot/skills/github/SKILL.md

View only the logs for failed steps within a specific workflow run. This is useful for quickly debugging issues. Use `--repo owner/repo` to specify the repository.

```bash
gh run view <run-id> --repo owner/repo --log-failed
```

--------------------------------

### Manage DeepCode CLI Sessions

Source: https://github.com/hkuds/deepcode/blob/main/README.md

Commands for listing, showing, resuming, and attaching tasks to persistent CLI sessions. Sessions are stored under `~/.deepcode/sessions/<id>/`.

```bash
# Session management from the shell
python cli/main_cli.py session list
python cli/main_cli.py session show <session_id>
python cli/main_cli.py session resume <session_id>   # show history, then enter interactive mode
python cli/main_cli.py --session <session_id> --file paper.pdf
```

--------------------------------

### Configure Nanobot for Discord

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Enable and configure the Discord channel integration. Ensure MESSAGE CONTENT INTENT is enabled in Discord bot settings. Replace YOUR_BOT_TOKEN and YOUR_USER_ID.

```json
{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["YOUR_USER_ID"]
    }
  }
}
```

--------------------------------

### Add One-Time Cron Reminder

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/workspace/TOOLS.md

Sets a one-time reminder for a specific date and time using nanobot cron. The time should be in ISO format.

```bash
# At a specific time (ISO format)
nanobot cron add --name "meeting" --message "Meeting starts now!" --at "2025-01-31T15:00:00"
```

--------------------------------

### Troubleshooting Feishu Bot Connection

Source: https://github.com/hkuds/deepcode/blob/main/README.md

If the Feishu bot is unresponsive, check the nanobot logs for errors. Verify that the Feishu App ID and Secret are correct and that the app is published with 'Long Connection' mode enabled.

```bash
./nanobot/run_nanobot.sh logs
```

--------------------------------

### Configure Channel Access Control

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/SECURITY.md

Define 'allowFrom' lists in the configuration to restrict access to specific user IDs or phone numbers for Telegram and WhatsApp channels. An empty list allows all users.

```json
{
  "channels": {
    "telegram": {
      "enabled": true,
      "token": "YOUR_BOT_TOKEN",
      "allowFrom": ["123456789", "987654321"]
    },
    "whatsapp": {
      "enabled": true,
      "allowFrom": ["+1234567890"]
    }
  }
}
```

--------------------------------

### Add Plugin Support to Workflow Service

Source: https://github.com/hkuds/deepcode/blob/main/workflows/plugins/USAGE.md

Integrate plugin functionality into the WorkflowService by initializing WorkflowPluginIntegration and running hooks at specific interaction points. This involves adding three lines of code to create context, run hooks, and handle potential cancellations.

```python
from workflows.plugins.integration import WorkflowPluginIntegration
from workflows.plugins import InteractionPoint

class WorkflowService:
    def __init__(self):
        self._tasks = {}
        self._subscribers = {}
        # 添加这一行
        self._plugin_integration = WorkflowPluginIntegration(self)

    async def execute_chat_planning(self, task_id, requirements, enable_indexing=False):
        # ... 原有代码 ...

        # ===== 添加插件支持 (仅需3行代码) =====

        # 1. 创建上下文
        context = self._plugin_integration.create_context(
            task_id=task_id,
            user_input=requirements,
            enable_indexing=enable_indexing,
        )

        # 2. 运行 BEFORE_PLANNING 插件 (需求分析)
        context = await self._plugin_integration.run_hook(
            InteractionPoint.BEFORE_PLANNING,
            context
        )

        # 检查是否被取消
        if context.get("workflow_cancelled"):
            return {"status": "cancelled", "reason": context.get("cancel_reason")}

        # 使用可能被增强的需求
        requirements = context.get("requirements", requirements)

        # ===== 原有的计划生成代码 =====
        planning_result = await run_chat_planning_agent(requirements, logger)

        # ===== 添加计划确认插件 =====
        context["planning_result"] = planning_result
        context = await self._plugin_integration.run_hook(
            InteractionPoint.AFTER_PLANNING,
            context
        )

        if context.get("workflow_cancelled"):
            return {"status": "cancelled", "reason": context.get("cancel_reason")}

        # 使用可能被修改的计划
        planning_result = context.get("planning_result", planning_result)

        # ===== 继续原有的代码实现流程 =====
        ...
```

--------------------------------

### DingTalk Channel Configuration

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/README.md

Configure nanobot to use DingTalk. Requires AppKey (Client ID) and AppSecret (Client Secret). Uses Stream Mode, no public IP required.

```json
{
  "channels": {
    "dingtalk": {
      "enabled": true,
      "clientId": "YOUR_APP_KEY",
      "clientSecret": "YOUR_APP_SECRET",
      "allowFrom": []
    }
  }
}
```

--------------------------------

### Add a Scheduled Reminder using nanobot cron

Source: https://github.com/hkuds/deepcode/blob/main/nanobot/workspace/AGENTS.md

Use this command to schedule a one-time reminder. Ensure USER_ID and CHANNEL are correctly extracted from the current session.

```shell
nanobot cron add --name "reminder" --message "Your message" --at "YYYY-MM-DDTHH:MM:SS" --deliver --to "USER_ID" --channel "CHANNEL"
```