# TourGuide

JSON navigation guides that control what an AI reads

- Role: Creator & Maintainer
- Period: Dec 2025 – present
- Status: active
- Domain: ai
- Type: case-study
- Open source: yes
- Source code: https://github.com/kilgor/TourGuide
- Human page: https://alicem.dev/projects/tourguide

## Summary

Human-authored, JSON-only guides that define exactly what an AI reads, in what order, and what to skip. It reduces hallucination caused by unstructured codebase exploration.

## Case study

### Problem

When you switch between AI assistants, each new one needs your codebase explained again. Unguided exploration of a large codebase is also where hallucinations start: the AI reads the wrong files, in the wrong order, and fills the gaps with guesses.

### Approach

A guide is a JSON file that you write once, with AI help. It says what to read, in what order, what to skip, and where the checkpoints are. TourGuide never discovers, generates or decides anything; the human is the cartographer. Setup takes 15 to 30 minutes for a small project and one to two hours for a large one: copy a template, explore the codebase with an AI, customize the guide, then test it on a fresh AI session.

### Architecture

A root tourguide.json links to sub-guides for deep dives, forming a map of interconnected JSON files. The repository ships templates, real examples, documentation and a demo you can show to an AI assistant.

### Result

Published open source under Apache 2.0. Used in production as the codebase navigation layer inside ONE TOOL, so every new AI session starts from the same complete context.

## Highlights

- Apache 2.0 open source with templates and real-world examples
- No code generation and no automation: pure context architecture
- Used in production as the codebase navigation layer inside ONE TOOL

## Technologies

Context Engineering, JSON, AI Agent Navigation, Open Source