Build your first Keating workspace

Start with a checkout

Keating uses Bun and a Devenv environment to keep its development tools and task graph together. The root package contains the CLI and pedagogy engine. The web app has its own package and build. Enter the environment before installing or running tasks.

git clone https://github.com/Diogenesoftoronto/keating.git
cd keating
devenv shell
devenv tasks run keating:install
devenv tasks list

Make an inspectable artifact

A lesson plan or concept map is a useful first check because these local artifact builders do not need a hosted model. Run commands from the directory whose learner state and outputs you want to use. The generated files live below that directory's .keating folder.

• plan creates a structured teaching plan; it does not execute a conversation.
• map writes editable Mermaid source.
• verify creates a checklist for checking claims; creating the checklist alone does not verify those claims.

bun src/cli/main.ts plan derivative
bun src/cli/main.ts map derivative
bun src/cli/main.ts verify derivative

Connect an interactive teacher

The interactive shell uses Pi for model execution. Run setup to select the provider, model, thinking level, and runtime preference, then doctor to inspect the configuration. The default standalone-only runtime preference expects a working pi binary on PATH; doctor and setup are the first places to look when the shell cannot start.

Hosted inference requires provider credentials or a connected Not Organic account. Local artifact generation and model-backed teaching are separate checks: a successful plan does not prove the provider connection works.

bun src/cli/main.ts setup
bun src/cli/main.ts doctor
bun src/cli/main.ts shell

# Inside the shell:
/learn derivative

Run the browser app

The browser app uses React, TanStack Router, Vite, and Nitro. The development task starts the web development server. Production output needs both the Vite client build and the Nitro server build; building Vite alone is not a complete production build.

devenv tasks run keating:web

# Production builds:
devenv tasks run keating:web-build
devenv tasks run keating:build-all

Choose a useful first change

• Teaching behavior: begin with pi/prompts/learn.md and pi/skills/adaptive-teaching/SKILL.md.
• Artifact logic: begin with src/core/lesson-plan.ts, topics.ts, or map.ts.
• Browser experience: begin with web/src/components/ and web/src/hooks/useKeatingAgent.tsx.
• Terminal experience: begin with src/tui/ and the Pi runtime adapter.
• Native mobile: begin with mobile/README.md; Android setup has its own toolchain and verification tasks.

Verify the boundary you changed

Use the existing Bun tests for local behavior and injected model doubles for deterministic checks. Run the relevant package's tests and build. A browser interaction, a real provider exchange, a packaged desktop build, and a deployed service each need their own evidence.

devenv tasks run keating:test
devenv tasks run keating:test-web
devenv tasks run keating:build