# claude-code

Adopt this skill: https://proskills.md/skills/other/rayp11-questchain-skills-claude-code

Page: https://proskills.md/skills/other/rayp11-questchain-skills-claude-code
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/claude-code/SKILL.md
size: 3303
upstream: https://github.com/rayp11/questchain/blob/master/skills/claude-code/SKILL.md

````text
---
name: claude-code
description: Delegate coding tasks to Claude Code, an expert AI coding agent powered by Anthropic
---

# Claude Code Skill

## When to Use

Use the `claude_code` tool when the user asks you to:
- Write, create, or generate code
- Debug or fix code issues
- Refactor or improve existing code
- Create new files or projects
- Make changes to a codebase
- Explain code in detail
- Write tests
- Review or analyze code

Look for keywords like: "code", "write", "build", "implement", "fix", "debug", "refactor", "create a script", "make a program", "review", or any request that involves programming.

## When NOT to Use

Do not use `claude_code` for:
- General knowledge questions
- Web searches
- File reading (use your built-in read_file tool)
- Simple shell commands
- Memory/notes operations

## Parameters

### `task` (required)
The coding task or prompt. Be specific about what to build/change, which files are involved, and any constraints.

### `complexity` (optional, default: `"medium"`)
Controls which Claude model and timeout to use:

| Value | Model | Timeout | Use When |
|-------|-------|---------|----------|
| `"simple"` | Haiku (fast) | 5 min | Explanations, small edits, quick code questions |
| `"medium"` | Sonnet (capable) | 10 min | Most coding tasks, bug fixes, new features |
| `"complex"` | Sonnet (capable) | 15 min | Large refactors, multi-file changes, complex implementations |

### `mode` (optional, default: `"code"`)
Controls what Claude Code is allowed to do:

| Value | Permissions | Use When |
|-------|------------|----------|
| `"code"` | Read + write/edit files | You need code changes made (default) |
| `"review"` | Read-only access | Code review, analysis, understanding code without changing it |

### `context` (optional)
Additional project context to include with the task. Pass relevant information from the conversation that Claude Code might need, such as error messages, user requirements, or file paths mentioned earlier.

## Examples

### Simple task — explain code
```
claude_code(
    task="Explain what the create_genie_agent function does in genie/agent.py",
    complexity="simple",
    mode="review"
)
```

### Medium task — fix a bug
```
claude_code(
    task="Fix the bug where web_search results are not being displayed correctly",
    complexity="medium",
    mode="code",
    context="The user reported that search results show 'None' instead of snippets. Error traceback points to tools/web_search.py line 15."
)
```

### Complex task — implement a feature
```
claude_code(
    task="Add a new REST API endpoint that exposes Genie as an HTTP service with streaming responses",
    complexity="complex",
    mode="code",
    context="Should use FastAPI, support SSE streaming, and integrate with the existing agent.py create_genie_agent function."
)
```

### Code review
```
claude_code(
    task="Review the Telegram bot integration for security issues and potential improvements",
    complexity="medium",
    mode="review"
)
```

## Writing Good Task Prompts

Be specific in the task you send to Claude Code. Include:
- What to build or change
- Which files or languages are involved
- Any constraints or requirements the user mentioned
- Use `context` to pass error messages, stacktraces, or conversation details
````

## File: README.md
upstream: https://github.com/rayp11/questchain/blob/master/README.md

````text
<div align="center">

<img src="assets/QuestChain-LOGO.png" alt="QuestChain" width="400"/>

# Truly Local. Always On. Ready for Tasks.

### Your AI assistant, running on your hardware, working for you around the clock.

[![Python](https://img.shields.io/badge/Python-3.13%2B-3776AB?logo=python&logoColor=white)](https://python.org)
[![Ollama](https://img.shields.io/badge/Ollama-Local%20LLM-black?logo=ollama&logoColor=white)](https://ollama.com)
[![License](https://img.shields.io/badge/License-MIT-green)](https://github.com/RayP11/QuestChain/blob/master/LICENSE)

[![Discord](https://img.shields.io/badge/Discord-Join%20the%20Community-%235865F2?logo=discord&logoColor=white&style=for-the-badge)](https://discord.gg/C8Rc3u7KKx)

<img src="assets/QuestChain-short-demo.gif" alt="QuestChain demo" width="800"/>

<img src="assets/chat-ui.png" alt="QuestChain chat" width="800"/>

</div>

---

QuestChain is an AI assistant that runs entirely on your machine. No cloud, no subscriptions, no usage limits. Just your hardware running a capable local model 24/7. It reads your files, runs shell commands, searches the web, schedules jobs, and works through your task list while you sleep. Nothing leaves your machine.

---

## Contents

- [Why QuestChain?](#why-questchain)
- [RPG Progression](#rpg-progression)
- [Cron Jobs](#cron-jobs)
- [Install](#install)
- [What It Can Do](#what-it-can-do)
- [Built for the Edge](#built-for-the-edge)
- [It Codes Itself](#it-codes-itself)
- [Terminal Commands](#terminal-commands)
- [Telegram Setup](#telegram-setup)
- [Most Tested Models](#most-tested-models)
- [Contributing](#contributing)
- [Built With](#built-with)

---

## Why QuestChain?

I tried [OpenClaw](https://github.com/OpenClaw-AI/OpenClaw) and was having a lot of fun playing around with it. However, I couldn't afford the api token cost and I wasn't able to run local models quickly without having to buy even more expensive hardware. So I was inspired to create a framework which could run models as small as 3B autonomously and productively.

QuestChain is that framework: a party of micro agents all jam-packed with tool loadouts for specific tasks, fully autonomous, and with a twist of gamification.

### At a glance

| | **QuestChain** |
|---|---|
| Language | Python |
| Lines of code | ~9,000 |
| Source files | 40 |
| Multi-surface (CLI, Telegram, Web) | ✅ |
| RPG progression | ✅ |
| Custom async agent engine | ✅ |

---

## RPG Progression

<div align="center">
<img src="assets/agents-select.gif" alt="QuestChain agent page" width="800"/>
</div>

QuestChain isn't just a tool. It's a companion you build over time. Every agent starts at Level 1 and earns XP through real work: tool calls, completed tasks, background jobs, and extended conversations. The more your agent works, the stronger it gets.

Each agent has:

- Levels (1-20)
- A class
- Achievements
- Progression
- Behavior
- Tools

### Classes

Classes are QuestChain's micro-agent system. Each class is a specialized agent with its own role, tool loadout, and independent progression. Keeping agents focused on a single domain is best practice for local models. A smaller context, fewer tools, and a clear identity means better decisions and fewer hallucinations.

| Class | Icon | Specialty | Tool Preset |
|---|---|---|---|
| Custom | 🌀 | You decide | You configure |
| Coordinator | 🧭 | Routes work and communicates status | No execution tools |
| Keeper | 📚 | Files & knowledge | File tools |
| Explorer | 🔭 | Research & discovery | Web search + browse |
| Builder | ⚒️ | Code & systems | Files and shell; optional Claude Code |
| Planner | 🔮 | Planning & strategy | File tools |
| Scheduler | ⏱️ | Automation | Cron only |

---

## Coordinator and specialists

Chat with **Perseus** to route work to **Argus** (research), **Athena** (workspace knowledge), **Talos** (building), or **Zeus** (planning and advice). Each specialist streams its own response under its own name. Direct chat is always available.

Perseus uses the same chat engine as every other agent: he can answer you directly or hand your request to a specialist. A conversation is one shared thread in the interface, with separate saved context for each agent. Perseus also receives attributed records of the other agents' requests, replies, and outcomes in that thread, so he can route follow-ups and remember completed work. Specialists see their own interactions, including work routed to them and any context supplied with a handoff. Starting a new thread starts fresh for all agents; reopening one restores their saved context. Every agent summarizes older history as the estimated context budget fills, including during tool-call loops. Use the web chat's conversation selector, terminal `/history`, or Telegram `/history` to resume a thread.

Athena's workspace knowledge role includes creating, editing, and deleting files with the built-in `write_file`, `edit_file`, and `delete_file` tools. These tools are enabled by default for the Keeper role and remain configurable per agent. Deletion accepts individual workspace files, rejects directories and symbolic links, and stays inside the workspace. Existing untouched Keeper presets gain deletion once when upgrading; customized permissions are preserved.

Create additional agents in the web UI, terminal, or Telegram with a name, tools, system prompt, and guidance describing when the coordinator should call them. Legacy agents are archived under `~/.questchain/legacy` and can be migrated explicitly through any interface. [Agent guide](docs/agent-classes.md).

## Cron Jobs

Automate recurring work from the **Cron Jobs** page, the terminal `/cron` menu, or Telegram `/cron` commands. Jobs share one persistent scheduler and run while QuestChain is open.

Each job has a name, instructions, a schedule, timezone, and assigned agent. The web UI uses a standard time selector; terminal and Telegram commands accept cron expressions. Create, edit, pause, resume, run now, or delete a job. The web UI shows its next run, last status, and result. Results also appear in the terminal, or on Telegram when connected.

```text
/cron add Morning summary | 0 9 * * mon-fri | America/New_York | Summarize my notes
/cron list
/cron show JOB_ID
/cron pause JOB_ID
/cron resume JOB_ID
/cron run JOB_ID
/cron delete JOB_ID
```

Use weekday names (`mon`–`sun`); numeric weekdays follow APScheduler: Monday=0, Sunday=6. Pausing or deleting a job prevents future runs; a run already underway finishes.

The old quest folder and periodic quest runner have been retired. Existing quest files remain on disk and are no longer executed. Recreate desired recurring tasks as cron jobs. The `--quests` and `--no-quests` startup flags have been removed.

---

## Install

### Step 1: Install Ollama

Download and install Ollama from [ollama.com/download](https://ollama.com/download), then start it:

```bash
ollama serve
```

Leave it running, then open a new terminal for the next step.

### Step 2: Install QuestChain

**Windows:** open PowerShell and run:

```powershell
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/RayP11/QuestChain/master/install.ps1 | iex"
```

**macOS / Linux:** open a terminal and run:

```bash
curl -fsSL https://raw.githubusercontent.com/RayP11/QuestChain/master/install.sh | bash
```

### Step 3: Run

```
questchain start
```

On first run, QuestChain walks you through a short onboarding conversation and optionally sets up Telegram. After that, it remembers who you are.

> **Web search (optional):** Run `/tavily` inside QuestChain to set up your free [Tavily API key](https://tavily.com) and enable web search and browsing.

### Startup Cheat Sheet

```bash
questchain start                      # Start with default model
questchain start -m qwen3:4b          # Use a specific model
questchain start -t <thread-id>       # Resume a previous conversation
questchain start --web                # Start with web UI (gateway + CLI)
```

### Updating
````
