Getting Started

Getting Started

This page covers Mode A: running Skillful Alhazen interactively with Claude Code on your local machine.

Mode	Best for	Guide
A. Claude Code (local)	Development, exploration, research sessions	This page
B. OpenClaw on Mac Mini	Persistent local service with Telegram triage	Deployment
C. OpenClaw on VPS	Always-on production deployment	Deployment

---

Prerequisites

Verify all prerequisites before attempting the build:

# uv (Python package manager) — must print a version string
uv --version
# If missing: curl -LsSf https://astral.sh/uv/install.sh | sh

# Docker — must succeed without errors
docker info
# If failing: start Docker Desktop (macOS) or `sudo systemctl start docker` (Linux)

# Docker Compose v2 — must print "Docker Compose version v2.x.x"
docker compose version
# NOTE: use `docker compose` (space), NOT the old `docker-compose` (hyphen)

macOS: Docker Desktop includes Docker Compose v2 — just start Docker Desktop. Linux: Install docker-compose-plugin (not the standalone docker-compose v1).

---

Installation

1. Clone and build

git clone https://github.com/GullyBurns/skillful-alhazen
cd skillful-alhazen
make build

make build runs four steps in sequence:

1. build-env — installs Python dependencies via uv sync --all-extras
2. build-skills — resolves skills-registry.yaml → local_skills/ + wires .claude/skills/ symlinks
3. build-dashboard — wires skill dashboard components into Next.js
4. build-db — starts TypeDB container and loads all schemas

2. Verify the build

# TypeDB container should show (healthy)
docker ps --filter "name=alhazen-typedb" --format "table {{.Names}}\t{{.Status}}"

# TypeDB driver should import cleanly
uv run python -c "import typedb.driver; print('TypeDB driver OK')"

# Skills should be wired
ls local_skills/

# Overall status
make status

3. Open Claude Code

claude

That's it. Claude reads the skill files automatically. Talk to it in natural language.

---

First Session Examples

Scientific literature research

You: Search PubMed for papers about CRISPR base editing published in 2023-2024
You: How many results are there?
You: Ingest the top 30 papers into my knowledge graph
You: What are the main themes across these papers?
You: Remember that NGG PAM sequences are the primary constraint on target site selection

Job hunting

You: Ingest this job posting: https://example.com/senior-ml-engineer
You: Analyze my fit for this position
You: What skill gaps do I have for this role?
You: Add a note that this company uses PyTorch, not TensorFlow

Rare disease investigation

You: What are the pathophysiological mechanisms underlying Marfan syndrome?
You: Search DisMech for diseases involving the RAS/MAPK pathway
You: I want to investigate Fibrodysplasia Ossificans Progressiva — what MONDO ID does it have?

---

Key Make Targets

Target	What it does
make build	Full build (run this after cloning or updating)
make db-start	Start TypeDB container
make db-stop	Stop TypeDB container
make db-init	Reload all schemas into running TypeDB
make skills-update	Re-clone external skills from upstream
make status	Show TypeDB container status and skills count
make qdrant-start	Start Qdrant (needed for semantic search)

---

Troubleshooting

Symptom	Cause	Fix
docker info fails	Docker not running	Start Docker Desktop (macOS) or sudo systemctl start docker
make build-db hangs > 60s	TypeDB slow to start	docker logs alhazen-typedb; increase Docker memory in Desktop settings
Port 1729 in use	Another TypeDB instance	docker ps -a | grep 1729 then docker stop <id>
External skills absent from local_skills/	Git clone failed	make skills-update; check network/git access
Schema fails [SYR1] type not found	Missing entity keyword	See Skill Architecture — add entity keyword before type name in schema.tql
TypeDB auth error	Wrong credentials	Default: username=admin, password=password
Queries return empty after new skill	Schema not reloaded	Re-run make db-init after make build-skills

---

Optional: Semantic Search

The scientific-literature skill can embed papers and perform semantic (similarity-based) search. This requires:

1. Qdrant vector store: make qdrant-start
2. Voyage AI API key: export VOYAGE_API_KEY=<your-key> (get one at dash.voyageai.com)

Then use the embed and search-semantic commands from the scientific-literature skill.

---

Next Steps

• Skill Architecture — how to build your own skill
• Deployment — set up a persistent OpenClaw instance
• Skills: Scientific Literature — literature search and corpus building
• Skills: Jobhunt — job application tracking