tillm

Text-interface LLM control plane for the semcod/coru ecosystem.

Drives shell and terminal clients (aider, claude, codex, gemini, qwen-code, opencode, devin) from one registry and execution pipeline. Pair with gillm for graphical control (focus, inject, capture, orchestrator DSL).

AI Cost Tracking

• 🤖 LLM usage: $2.4161 (35 commits)
• 👤 Human dev: ~$826 (8.3h @ $100/h, 30min dedup)

Generated on 2026-06-08 using openrouter/deep/deep-v4-pro

---

Package	Interface	Role
tillm	text / shell	vendor CLI registry, drive, multi-client matrix, transports
gillm	graphical	GUI domain + *2gillm adapters (REST :8220, MCP, …)

Contents

• Architecture
• Control layer packages
• Installation
• Quick start
• Shell clients
• Multi-client orchestration
• Configuration
• Version and updates
• Testing
• Documentation
• License

Architecture

SUMD (description) → DOQL/source (code) → taskfile (automation) → testql (verification)

Sources: SUMD.md · app.doql.less

flowchart TB
  subgraph adapters [Input adapters — packages]
    NL[nlp2tillm]
    URI[uri2tillm]
    CLI[cli2tillm]
    MCP[mcp2tillm]
    REST[rest2tillm]
  end

  subgraph control [Control layer]
    DSL[dsl2tillm.dispatch]
    SCH[JSON Schema]
    ES[(EventStore)]
  end

  subgraph domain [Domain — src/tillm]
    REG[registry]
    DRV[drive / matrix]
    TR[binary / docker / http]
  end

  NL --> DSL
  URI --> DSL
  CLI --> DSL
  MCP --> DSL
  REST --> DSL
  DSL --> SCH
  DSL --> REG
  DSL --> DRV
  DRV --> TR
  DSL --> ES

Loading

Control layer packages

Package	Role	Port
dsl2tillm	DSL + JSON Schema + CQRS bus	—
uri2tillm	tillm:// → DSL	—
nlp2tillm	NL → DSL	—
cli2tillm	Shell REPL	—
mcp2tillm	MCP stdio	—
rest2tillm	FastAPI /v1/dsl	8216

Details: docs/control-layer.md · packages/README.md

Installation

Core (editable dev)

git clone <repo> tillm && cd tillm
pip install -e ".[dev]"

Control layer (all *2tillm packages)

bash packages/install-dev.sh

Optional ecosystem siblings

pip install -e ../nlp2dsl ../intract ../redsl ../proxym ../llx   # adjust paths

Note: tillm and *2tillm are not yet published on PyPI. Use editable installs from the repo.

Quick start

# List registered shell clients
tillm clients

# Dry-run (plans command, saves prompt, does not execute)
tillm drive --client aider --prompt "Refactor ticket PLF-1"

# Execute (requires client env vars — see configuration)
tillm drive --client aider --prompt "Refactor ticket PLF-1" --execute

# NLP → drive intent
tillm nlp "aider: napraw testy"

# Ecosystem validation
tillm validate

# Control layer
dsl2tillm exec HEALTH
rest2tillm serve --port 8216

tillm drive always saves the prompt under .koru/tillm/prompts/ before dry-run or execute.

Shell clients

Eight clients in the registry. Live status: tillm clients (ok / ~ / --).

Client	Headless	Automation profile
claude-code	claude -p	--dangerously-skip-permissions
aider	--message-file	—
codex	codex exec	--dangerously-bypass-approvals-and-sandbox
gemini-cli	gemini -p	--yolo
qwen-code	qwen -p	—
opencode	opencode run	—
devin	devin -p	--permission-mode dangerous
cline	dry-run only	—

Per-client setup: docs/clients/

Multi-client orchestration

tillm drive --clients aider,codex --prompt "review auth" --parallel 2
tillm drive --all --prompt "review" --execute --profile automation
tillm drive --all --prompt "review" --quorum 2 --fail-fast

DSL equivalent:

DRIVE_MATRIX CLIENTS aider,codex PROMPT "review" PARALLEL 2
DRIVE_MATRIX ALL PROMPT "review" EXECUTE true PROFILE automation

Configuration

Copy .env.example → .env. tillm auto-loads <project>/.env (via project_env + optional env2llm):

# .env — tillm reads this automatically from project root
OPENROUTER_API_KEY=sk-or-v1-...
LLM_MODEL=openrouter/deepseek/deepseek-v4-pro
AIDER_MODEL=openrouter/deepseek/deepseek-v4-pro   # optional; defaults from LLM_MODEL

tillm drive --client aider --prompt "fix tests" --execute

Install env2llm integration: pip install -e ".[env]" or pip install -e ../env2llm

Full reference: docs/configuration.md

Environment variables

Variable	Default	Purpose
TILLM_DEFAULT_CLIENT	aider	Default for tillm nlp
TILLM_EXECUTE_PROFILE	default	automation for CI
TILLM_BACKEND	binary	docker for compose exec
TILLM_NLP2DSL	off	External NLP2DSL bridge

Optional NLP2DSL bridge

export TILLM_NLP2DSL=1
export NLP2DSL_BACKEND_URL=http://localhost:8010
tillm nlp "uruchom claude dla ticketu PLF-123"

Without the service, tillm uses a deterministic local parser.

Version and updates

Check installed version

pip show tillm | grep Version          # core: 0.1.32
cat VERSION
pip show dsl2tillm rest2tillm         # control layer: 0.1.0
tillm clients
tillm validate

Update from repo (current workflow)

cd tillm
git pull
pip install -e ".[dev]"
bash packages/install-dev.sh
python -m pytest tests/test_tillm.py packages/*/tests -q

Update vendor CLIs (independent)

pip install -U aider-chat
npm update -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli

When published to PyPI:

pip install -U tillm dsl2tillm uri2tillm nlp2tillm cli2tillm mcp2tillm rest2tillm

Testing

python -m pytest tests/test_tillm.py packages/*/tests -q
dsl2tillm validate-schema
dsl2tillm exec HEALTH

Examples

Runnable smoke tests per shell client (OpenRouter + tillm):

cp examples/openrouter/env.example .env   # set OPENROUTER_API_KEY
source examples/openrouter/load-env.sh
bash examples/aider/execute.sh
bash examples/run-all-dry-run.sh

See examples/README.md.

Documentation

Document	Description
examples/README.md	Per-client CLI smoke scripts
docs/README.md	Documentation index
docs/configuration.md	.env, OpenRouter, env vars
docs/control-layer.md	*2tillm packages
docs/clients/	Per-client setup
packages/README.md	Control layer quick reference
SUMD.md	Architecture description
CHANGELOG.md	Release history
TODO.md	Remaining work

License

Licensed under Apache-2.0.