Synoptik

Synoptik was built because in writing code using Claude in Javascript, Python, and Lisp, I found Claude needed documentation of architectures, tests, and decisions. If Claude code didn’t have that it would go about inspecting code to make decisions.

While there are several code indexing systems that build knowledge graphs over the code, Synoptik creates a knowledge graph over both the code and the documentation and anweers: where something is defined, what a change reaches, which decisions govern an area. It is written in Common Lisp and indexes itself. It was built by iteration of the use of Synoptik while building out a large Javascript and LISP project. Synoptik currently works with Common Lisp, JavaScript and Python source and YAML and Markdown documents, and it answers people and LLM agents over a console, a REST API and an MCP endpoint. A user interface against the REST API has not yet been built.

INSTALL.md takes a machine with SBCL to a passing suite. CONTRIBUTING.md says how to change it, and contributors follow the code of conduct. Synoptik is MIT-licensed (LICENSE), and THIRD-PARTY-LICENSES.md lists the licence of each library it loads.

Synoptik now includes a web server app that provides a way to navigate, edit, and interact with coding agents at the document level. Using this tool its easy to write and review requirements, have an agent expand those requirements, build and review designs, create plans, and execute code. Documents and their relatioships can be navigated including dependant code. This provides a powerful way of controlling an agent and writing code at the requirments and design level and letting the agent create and test the code.

Synoptik was called Synoptik until October 2026. The code keeps the old name: the ASDF systems and packages are synoptik-*, the MCP tools are synoptik_*, and the index directory is .synoptik/.

Why

An agent editing code has two ways to learn what a change touches. It can read files until it believes it has seen enough, or it can grep. Grep matches spelling. grep -rn slurp-file src/ returned 27 lines, and four of them were a docstring, an export, a comment and the definition. When two packages define or re-export the same name, grep cannot say which one a call reaches. Either way the agent rebuilds the structure of the tree from scratch at the start of every session, and the documents that record why the code is the way it is sit in other files that it never opens.

Synoptik indexes the tree once and answers from the knowledge graph using both lexical matching and semantic matching. Three cases from VALUE.md, give some illustration of the usefulness of Synoptik:

• describe slurp-file returned 16 source callers and 2 tests, by location, across three systems. Deciding whether the function was safe to delete from