Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Implementation Notes

This page records the selected implementation direction for Toolang v1.

Language and packaging

  • implementation language: Python
  • supported package/runtime range: >=3.10
  • default local development version: 3.13
  • build backend: hatchling
  • test runner: pytest

Python keeps iteration fast while covering CLI, HTTP, SQLite, and model APIs well.

Selected stack

  • syntax Tree-sitter via the published tree-sitter-toolang Python extension
  • CLI Typer
  • validation and serialization Pydantic v2
  • model execution official OpenAI Python SDK
  • HTTP server FastAPI and Uvicorn
  • HTTP client httpx
  • local storage SQLite

Package boundaries

Current internal packages:

  • toolang.program parsing and syntax analysis
  • toolang.agent agent resolution, managed local-agent operations, preparation, and registry
  • toolang.runtime prompt build, invoke, chat, and server runtime
  • toolang.caps refs, sync orchestration, materialization, and runtime cap views
  • toolang.concepts shared identity, execution, layout, sandbox, capability, and persisted-state constructs
  • toolang.bus shared bus projection and bus API
  • toolang.sandbox sandbox runtime helpers
  • toolang.cli CLI surfaces and command registration
  • toolang.web shared FastAPI app helpers

Storage choices

SQLite is the primary local storage layer.

Current or expected uses:

  • chat transcripts ${AGENT_ROOM}/chats/chats.db
  • known-agent and running-agent registry ${TOOLANG_ROOT}/agents.db
  • shared bus projection ${TOOLANG_ROOT}/bus/events.db
  • future execution truth layer runs, threads, turns, and steps

Other durable formats:

  • Markdown skills, services, prompts, psyches, tasks, chores, and will
  • JSON sync state, prompt traces, API output, runtime metadata
  • TOML authored runtime and plugin configuration

Parser and sync direction

Implementation rules:

  • the Tree-sitter grammar is the syntax source of truth
  • runtime parsing uses Tree-sitter output, not a second handwritten parser
  • sync writes durable generated artifacts that can be reused without reparsing unchanged sources
  • synced state under .toolang/sync/ is the execution boundary, not raw source

Repository boundaries

This repository owns:

  • runtime code
  • CLI code
  • sync integration
  • the internal toolang.caps package until it is split out if needed
  • tests for runtime behavior

Sibling repositories own:

  • the Tree-sitter grammar source
  • editor packages
  • the docs site

Simplicity rules

The v1 implementation should stay intentionally small:

  • local-first runtime
  • no required framework layer above the model SDK
  • no separate package-manager binary
  • simple background supervision
  • shared grammar for runtime and editor parsing
  • synced execution state as the main runtime boundary

Read next

© 2026 Toolang