claude-code

Truly Local. Always On. Ready for Tasks.

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

---

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?
• RPG Progression
• Cron Jobs
• Install
• What It Can Do
• Built for the Edge
• It Codes Itself
• Terminal Commands
• Telegram Setup
• Most Tested Models
• Contributing
• Built With

---

Why QuestChain?

I tried 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

---

RPG Progression

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.

---

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.

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.

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.

/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, then start it:

ollama serve

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

Step 2: Install QuestChain

Windows: open PowerShell and run:

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

macOS / Linux: open a terminal and run:

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 and enable web search and browsing.

Startup Cheat Sheet

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 an installed copy

Exit QuestChain with Ctrl+C, Ctrl+D, or /exit, then run:

questchain --update

If an older version's updater fails to launch, update directly with:

uv tool install git+https://github.com/RayP11/QuestChain@master --reinstall

Restart QuestChain after updating. Your settings, agents, and conversation history remain in the data directory.

Clone & Run (alternative)

If you want to clone the repo directly, modify the code, or run from source:

git clone https://github.com/RayP11/QuestChain.git
cd QuestChain

Option A — uv sync (recommended, no manual activation needed):

uv sync
uv run python -m questchain

Option B — uv with venv:

uv venv
source .venv/bin/activate   # macOS / Linux
.venv\Scripts\activate      # Windows
uv pip install -e .
python -m questchain

Option C — plain pip with venv:

python -m venv .venv
source .venv/bin/activate   # macOS / Linux
.venv\Scripts\activate      # Windows
pip install -e .
python -m questchain

Ollama must still be running before starting QuestChain. See Step 1 above.

---

What It Can Do

• 🔍 Web Search & Browse: Find current information and extract full page content via Tavily (optional)
• 📁 **File O