Quick Start

This guide gets you from zero to a working Sibyl setup in about 5 minutes.

Prerequisites

Make sure you have:

• Python 3.13+ installed
• Docker (for FalkorDB)
• An OpenAI API key

Step 1: Start the Infrastructure

# Start FalkorDB
docker run -d \
  --name falkordb \
  -p 6380:6379 \
  falkordb/falkordb:latest

Step 2: Install and Configure

# Clone and install
git clone https://github.com/hyperb1iss/sibyl.git
cd sibyl
uv sync

# Configure
cp apps/api/.env.example apps/api/.env

Edit apps/api/.env and set:

SIBYL_OPENAI_API_KEY=sk-your-openai-key
SIBYL_JWT_SECRET=any-secret-string-for-development

Step 3: Start the Server

# Start everything
moon run dev

# Or just the API
cd apps/api && uv run sibyl-serve

The server is now running on http://localhost:3334.

Step 4: Configure the CLI

# Set the server URL
sibyl config set server.url http://localhost:3334/api

# Check health
sibyl health

Step 5: Create Your First Entity

Let's add some knowledge to the graph:

# Add a learning
sibyl add "Python async gotcha" "Always use asyncio.gather() for concurrent awaits, not sequential awaits in a loop"

You should see:

Added: Python async gotcha (id: episode_abc123)

Step 6: Search for Knowledge

# Search by meaning
sibyl search "async concurrency"

The search will find your learning even though you searched for different words - that's semantic search in action.

Step 7: Create a Task

Tasks require a project, so let's create one:

# Create a project
sibyl project create --name "My First Project" --description "Learning Sibyl"

# Note the project ID from the output, then create a task
sibyl task create --title "Try Sibyl features" --project proj_abc123

Step 8: Manage Task Lifecycle

# List your tasks
sibyl task list --status todo

# Start working on a task
sibyl task start task_xyz

# Check what's in progress
sibyl task list --status doing

# Complete with learnings
sibyl task complete task_xyz --learnings "Sibyl CLI is intuitive!"

Step 9: Link a Directory (Optional)

If you're working on a specific project, link your directory:

# In your project directory
cd ~/my-project

# Link to a Sibyl project
sibyl project link proj_abc123

# Now task commands auto-scope to this project
sibyl task list --status todo  # Shows only tasks for linked project

Step 10: Explore the Graph

# List all projects
sibyl entity list --type project

# Find related entities
sibyl explore related entity_xyz

# See task dependencies
sibyl explore dependencies task_abc

Using with Claude Code

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "sibyl": {
      "type": "http",
      "url": "http://localhost:3334/mcp"
    }
  }
}

Now Claude can:

• Search your knowledge graph
• Track tasks
• Capture learnings
• Navigate relationships

The Agent Workflow

When working with Claude Code and Sibyl:

1. SEARCH FIRST     -> sibyl search "topic"
2. CHECK TASKS      -> sibyl task list --status doing
3. WORK & CAPTURE   -> sibyl add "learning" "description"
4. COMPLETE         -> sibyl task complete --learnings "..."

Common Commands Reference

Action	Command
Search knowledge	sibyl search "query"
Add a learning	sibyl add "title" "content"
List tasks	sibyl task list --status todo
Start a task	sibyl task start <id>
Complete a task	sibyl task complete <id> --learnings "..."
List projects	sibyl project list
Link directory	sibyl project link <id>
Check health	sibyl health

Output Formats

The CLI supports multiple output formats:

# Table (default, human-readable)
sibyl task list

# JSON (for scripting and agents)
sibyl task list --json

# CSV (for spreadsheets)
sibyl task list --csv

What's Next?

Now that you have Sibyl running:

1. Read the Philosophy - Introduction explains the "search, work, capture" mindset
2. Understand the Graph - Knowledge Graph explains how entities connect
3. Set Up Claude - Claude Code Integration for full AI agent support
4. Learn Entity Types - Entity Types to know what to capture

Tips for Success

Search First Before implementing anything, search the graph. Patterns, past solutions, and

gotchas might already be there. :::

Capture Non-Obvious Learnings If it took time to figure out, it's worth saving. Future you

(or your AI agent) will thank you. :::

Use Project Context Link your directories to projects. It keeps task lists focused and

prevents cross-project confusion. :::

Don't Skip Learnings The --learnings flag on task completion is where the real value

accumulates. Be specific about what you learned. :::