Skip to content

DOCS.md

Latest commit

 

History

History
123 lines (88 loc) · 4.38 KB

DOCS.md

File metadata and controls

123 lines (88 loc) · 4.38 KB
Raw

Chronos — Technical Documentation

Workspace structure

<workspace>/
├── sources/                  # Scanned page images
│   └── <source-name>/
│       └── png/
│           ├── page_0001.png
│           └── ...
├── data/                     # Outputs
│   └── <source-name>/       # Per-source extractions, summaries, JSON
├── skills/                   # Custom task definitions
│   └── <skill-name>/
│       └── SKILL.md          # Task instructions
├── memory/                   # Persistent memory
│   ├── MEMORY.MD             # Cross-source insights
│   └── <source-name>.md     # Per-source findings
├── sessions/                 # Conversation history (auto-generated)
└── .chronos/
    └── .env                  # GEMINI_API_KEY

Tools

The agent has these built-in tools for working with sources:

Tool Description
list_pages List available page IDs in the current source
ask_page Send a page image to the vision model with a prompt. Supports image cropping via bounding box and model selection
follow_up_question Continue the conversation about the last analyzed page (avoids re-sending the image)
show_page Display a page in the viewer without analysis. Supports bounding box cropping
show_text Display a text file in the viewer with optional passage highlighting
ask_pages_batch Batch-process multiple pages (requires explicit user confirmation)
change_source Switch to a different source at runtime

Standard file tools (read, write, edit, grep, find, ls) are also available for working with output files.

Vision models

The ask_page tool supports these Gemini models (default: gemini-3-flash-preview):

  • gemini-3-flash-preview
  • gemini-3.1-pro-preview
  • gemini-2.5-pro
  • gemini-2.5-flash
  • gemini-2.0-flash

Bounding box cropping

ask_page and show_page accept an optional bbox parameter with normalized coordinates (0–1):

{ "x": 0.0, "y": 0.0, "w": 0.5, "h": 0.5 }

This crops the image before sending it to the vision model or displaying it in the viewer.

Skills

Skills are self-contained task definitions that tell the agent what to do. They live in skills/<skill-name>/.

SKILL.md format

---
name: Extract Business Entries
description: Extract business names, addresses, and trades from directory pages
requires: schema.json
---

# Instructions for the agent

Analyze each page and extract all business entries...
  • name — human-readable name shown in the UI
  • description — one-line summary
  • requires — comma-separated filenames that must exist in the source directory (leave blank if none)

Run a skill by typing /skill:extract-entries in the pi terminal.

VS Code extension

Commands

Command Description
Chronos: Init Workspace Scaffold workspace structure and set API key
Chronos: Start Agent Session Launch the agent in a terminal with page viewer
Chronos: Show Page Open a specific page in the viewer
Chronos: Import Sources Batch-import files from a folder
Chronos: Window Setup Configure VS Code layout for Chronos

The extension provides clickable [view p.N] links in the terminal — click to open any page in the viewer.

Architecture

The VS Code extension communicates with the pi agent over HTTP. When a session starts, the extension spins up an HTTP server on a dynamic port and passes it to the agent via the CHRONOS_HTTP_PORT environment variable. The agent sends messages (page display, text updates, tool status) to the extension via HTTP POST.

Memory system

The agent maintains persistent memory across sessions:

  • Global memory (memory/MEMORY.MD) — cross-source insights, recurring conventions, abbreviation patterns, lessons learned
  • Per-source memory (memory/<source-name>.md) — document-specific findings like page ranges, section boundaries, layout observations, and structural notes

Memory files survive session restarts and are loaded automatically when the agent starts or switches sources.

Development

# Build the pi package
cd chronos && npm run build

# Build the VS Code extension
cd chronos-vscode && npm run build

# Package the VS Code extension
cd chronos-vscode && npm run package