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.0537 (57 commits)
- 👤 Human dev: ~$2253 (22.5h @ $100/h, 30min dedup)
Generated on 2026-07-19 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
- API providers
- 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
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:
tillmand*2tillmare 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/
API providers
A client is the tool tillm drives; a provider is the API or subscription
serving the model behind it. The same claude binary can talk to Anthropic
(native) or to any Anthropic-protocol vendor such as z.ai (GLM) by
overriding the endpoint + token environment for the subprocess.
| Provider | Kind | Token env | claude-code | aider/codex |
|---|---|---|---|---|
| anthropic | subscription | ANTHROPIC_API_KEY |
native | — |
| openai | api | OPENAI_API_KEY |
— | native |
| z.ai (GLM) | api | ZAI_API_KEY |
✓ | ✓ |
| deepseek | api | DEEPSEEK_API_KEY |
✓ | ✓ |
| google (Gemini) | api | GEMINI_API_KEY |
— | ✓ |
| openrouter | api | OPENROUTER_API_KEY |
— | ✓ |
| moonshot (Kimi) | api | MOONSHOT_API_KEY |
✓ | ✓ |
| xai (Grok) | api | XAI_API_KEY |
— | ✓ |
| groq | api | GROQ_API_KEY |
— | ✓ |
| mistral | api | MISTRAL_API_KEY |
— | ✓ |
| minimax (M2) | api | MINIMAX_API_KEY |
✓ | ✓ |
| qwen (DashScope) | api | DASHSCOPE_API_KEY |
— | ✓ |
| ollama | local | — | — | ✓ |
Ordered by popularity/recency; ✓ in the claude-code column means the vendor
exposes an Anthropic-compatible endpoint. Each provider carries a token_url
(where to create the key — shown before token prompts), curated model list,
and probe models. Default provider precedence: --provider > TILLM_PROVIDER
env > stored default (koru tillm can set it).
tillm providers # list with token status
tillm provider set z.ai # prompt for token (stored chmod 600), auto-probe
tillm provider test z.ai # live connectivity check
tillm drive --client claude-code --provider z.ai --prompt "..." --execute
export TILLM_PROVIDER=z.ai # provider for every drive (koru autonomy uses this)
Token precedence: process env var beats the store
(~/.config/tillm/providers.json, override dir via TILLM_CONFIG_DIR).
For z.ai the Anthropic-compatible endpoint (https://api.z.ai/api/anthropic)
drives claude-code with ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN; the
OpenAI-compatible endpoint serves aider/codex via OPENAI_API_BASE.
Interactive picker: koru tillm (koru-side UI over this registry).
Full guide: docs/providers.md.
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.
Metadata
Release files for tillm 0.1.44
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tillm-0.1.44.tar.gz | 72.2 kB | Without provenance | Details for tillm-0.1.44.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tillm-0.1.44-py3-none-any.whl | Python 3 | none | any | Details for tillm-0.1.44-py3-none-any.whl |
Total release size: 130.8 kB
Release files / tillm-0.1.44.tar.gz
| Download URL | tillm-0.1.44.tar.gz |
|---|---|
| Size | 72.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
989890a0646ceb24752de968a465580212a33fdd514e14a3119b30f06e4e2984
|
|
BLAKE2b-256 checksum How to use checksums |
98d4f4e046727e0593ac18a5ae3bc87638b4a44c3f22905d895a2bbdf4197c20
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Release files / tillm-0.1.44-py3-none-any.whl
| Download URL | tillm-0.1.44-py3-none-any.whl |
|---|---|
| Size | 58.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b0c05720511d2208de79211d31d99bc11d85dd39cd0871ef7098a8df7830d6c0
|
|
BLAKE2b-256 checksum How to use checksums |
e13491ccebf4939d16dde395653dbbff686c83d2a56cf231feebc3c6db65e0b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.7
|
Security for tillm 0.1.44
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.