clankit 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (188) hide show
  1. clankit-0.1.0/.gitignore +7 -0
  2. clankit-0.1.0/PKG-INFO +347 -0
  3. clankit-0.1.0/PROMPT.md +29 -0
  4. clankit-0.1.0/README.md +328 -0
  5. clankit-0.1.0/pyproject.toml +54 -0
  6. clankit-0.1.0/src/clankit/__init__.py +3 -0
  7. clankit-0.1.0/src/clankit/__main__.py +7 -0
  8. clankit-0.1.0/src/clankit/agent/__init__.py +0 -0
  9. clankit-0.1.0/src/clankit/agent/context.py +107 -0
  10. clankit-0.1.0/src/clankit/agent/events.py +391 -0
  11. clankit-0.1.0/src/clankit/agent/loop.py +609 -0
  12. clankit-0.1.0/src/clankit/agent/permissions.py +174 -0
  13. clankit-0.1.0/src/clankit/agent/prompts.py +255 -0
  14. clankit-0.1.0/src/clankit/agent/session.py +590 -0
  15. clankit-0.1.0/src/clankit/agent/state.py +346 -0
  16. clankit-0.1.0/src/clankit/agent/store.py +158 -0
  17. clankit-0.1.0/src/clankit/cli.py +257 -0
  18. clankit-0.1.0/src/clankit/commands.py +271 -0
  19. clankit-0.1.0/src/clankit/config/__init__.py +0 -0
  20. clankit-0.1.0/src/clankit/config/actions.py +182 -0
  21. clankit-0.1.0/src/clankit/config/catalog.py +631 -0
  22. clankit-0.1.0/src/clankit/config/fields.py +303 -0
  23. clankit-0.1.0/src/clankit/config/kdl.py +504 -0
  24. clankit-0.1.0/src/clankit/config/kdledit.py +386 -0
  25. clankit-0.1.0/src/clankit/config/kdllayout.py +541 -0
  26. clankit-0.1.0/src/clankit/config/kdlstarter.py +228 -0
  27. clankit-0.1.0/src/clankit/config/kdlsyntax.py +307 -0
  28. clankit-0.1.0/src/clankit/config/schema.py +267 -0
  29. clankit-0.1.0/src/clankit/config/store.py +167 -0
  30. clankit-0.1.0/src/clankit/headless.py +91 -0
  31. clankit-0.1.0/src/clankit/llm/__init__.py +0 -0
  32. clankit-0.1.0/src/clankit/llm/anthropic_provider.py +949 -0
  33. clankit-0.1.0/src/clankit/llm/compat/__init__.py +13 -0
  34. clankit-0.1.0/src/clankit/llm/compat/arguments.py +113 -0
  35. clankit-0.1.0/src/clankit/llm/compat/errors.py +298 -0
  36. clankit-0.1.0/src/clankit/llm/compat/models.py +94 -0
  37. clankit-0.1.0/src/clankit/llm/compat/profiles.py +185 -0
  38. clankit-0.1.0/src/clankit/llm/compat/stream.py +561 -0
  39. clankit-0.1.0/src/clankit/llm/compat/text_tools.py +269 -0
  40. clankit-0.1.0/src/clankit/llm/compat/wire.py +195 -0
  41. clankit-0.1.0/src/clankit/llm/openai_compat.py +208 -0
  42. clankit-0.1.0/src/clankit/llm/provider.py +105 -0
  43. clankit-0.1.0/src/clankit/llm/registry.py +212 -0
  44. clankit-0.1.0/src/clankit/llm/scripted.py +184 -0
  45. clankit-0.1.0/src/clankit/llm/types.py +409 -0
  46. clankit-0.1.0/src/clankit/orchestration/__init__.py +77 -0
  47. clankit-0.1.0/src/clankit/orchestration/architect.py +601 -0
  48. clankit-0.1.0/src/clankit/orchestration/base.py +112 -0
  49. clankit-0.1.0/src/clankit/orchestration/best_of_n.py +1129 -0
  50. clankit-0.1.0/src/clankit/orchestration/common.py +346 -0
  51. clankit-0.1.0/src/clankit/orchestration/demo.py +409 -0
  52. clankit-0.1.0/src/clankit/orchestration/escalate.py +623 -0
  53. clankit-0.1.0/src/clankit/orchestration/review.py +179 -0
  54. clankit-0.1.0/src/clankit/orchestration/review_loop.py +465 -0
  55. clankit-0.1.0/src/clankit/orchestration/solo.py +82 -0
  56. clankit-0.1.0/src/clankit/orchestration/task_tree.py +977 -0
  57. clankit-0.1.0/src/clankit/orchestration/test_loop.py +920 -0
  58. clankit-0.1.0/src/clankit/orchestration/ultra.py +463 -0
  59. clankit-0.1.0/src/clankit/orchestration/workflow/__init__.py +60 -0
  60. clankit-0.1.0/src/clankit/orchestration/workflow/account.py +173 -0
  61. clankit-0.1.0/src/clankit/orchestration/workflow/builtin/implement.py +117 -0
  62. clankit-0.1.0/src/clankit/orchestration/workflow/builtin/research.py +70 -0
  63. clankit-0.1.0/src/clankit/orchestration/workflow/builtin/review.py +90 -0
  64. clankit-0.1.0/src/clankit/orchestration/workflow/builtin/understand.py +105 -0
  65. clankit-0.1.0/src/clankit/orchestration/workflow/engine.py +935 -0
  66. clankit-0.1.0/src/clankit/orchestration/workflow/errors.py +30 -0
  67. clankit-0.1.0/src/clankit/orchestration/workflow/journal.py +84 -0
  68. clankit-0.1.0/src/clankit/orchestration/workflow/patterns.py +617 -0
  69. clankit-0.1.0/src/clankit/orchestration/workflow/saved.py +97 -0
  70. clankit-0.1.0/src/clankit/orchestration/workflow/script.py +553 -0
  71. clankit-0.1.0/src/clankit/orchestration/workflow/worker.py +283 -0
  72. clankit-0.1.0/src/clankit/orchestration/worktree.py +563 -0
  73. clankit-0.1.0/src/clankit/paths.py +41 -0
  74. clankit-0.1.0/src/clankit/runtime.py +207 -0
  75. clankit-0.1.0/src/clankit/skills/__init__.py +8 -0
  76. clankit-0.1.0/src/clankit/skills/candidate.py +217 -0
  77. clankit-0.1.0/src/clankit/skills/document.py +260 -0
  78. clankit-0.1.0/src/clankit/skills/evidence.py +427 -0
  79. clankit-0.1.0/src/clankit/skills/forge.py +471 -0
  80. clankit-0.1.0/src/clankit/skills/library.py +591 -0
  81. clankit-0.1.0/src/clankit/skills/redaction.py +114 -0
  82. clankit-0.1.0/src/clankit/skills/safety.py +195 -0
  83. clankit-0.1.0/src/clankit/skills/tool.py +143 -0
  84. clankit-0.1.0/src/clankit/themes/__init__.py +76 -0
  85. clankit-0.1.0/src/clankit/themes/colour.py +105 -0
  86. clankit-0.1.0/src/clankit/themes/custom.py +99 -0
  87. clankit-0.1.0/src/clankit/themes/legibility.py +134 -0
  88. clankit-0.1.0/src/clankit/themes/model.py +162 -0
  89. clankit-0.1.0/src/clankit/themes/palettes.py +468 -0
  90. clankit-0.1.0/src/clankit/themes/syntax.py +192 -0
  91. clankit-0.1.0/src/clankit/themes/textual.py +209 -0
  92. clankit-0.1.0/src/clankit/themes/web.py +59 -0
  93. clankit-0.1.0/src/clankit/tools/__init__.py +48 -0
  94. clankit-0.1.0/src/clankit/tools/base.py +388 -0
  95. clankit-0.1.0/src/clankit/tools/files.py +957 -0
  96. clankit-0.1.0/src/clankit/tools/search.py +842 -0
  97. clankit-0.1.0/src/clankit/tools/shell.py +594 -0
  98. clankit-0.1.0/src/clankit/tools/web.py +462 -0
  99. clankit-0.1.0/src/clankit/tui/__init__.py +31 -0
  100. clankit-0.1.0/src/clankit/tui/app.py +278 -0
  101. clankit-0.1.0/src/clankit/tui/composer.py +229 -0
  102. clankit-0.1.0/src/clankit/tui/editors.py +292 -0
  103. clankit-0.1.0/src/clankit/tui/entries.py +263 -0
  104. clankit-0.1.0/src/clankit/tui/format.py +173 -0
  105. clankit-0.1.0/src/clankit/tui/main.py +691 -0
  106. clankit-0.1.0/src/clankit/tui/pickers.py +338 -0
  107. clankit-0.1.0/src/clankit/tui/pump.py +70 -0
  108. clankit-0.1.0/src/clankit/tui/requests.py +305 -0
  109. clankit-0.1.0/src/clankit/tui/screens.py +229 -0
  110. clankit-0.1.0/src/clankit/tui/settings.py +925 -0
  111. clankit-0.1.0/src/clankit/tui/styles.py +266 -0
  112. clankit-0.1.0/src/clankit/tui/tasktree.py +619 -0
  113. clankit-0.1.0/src/clankit/tui/transcript.py +908 -0
  114. clankit-0.1.0/src/clankit/web/__init__.py +11 -0
  115. clankit-0.1.0/src/clankit/web/app.py +127 -0
  116. clankit-0.1.0/src/clankit/web/context.py +108 -0
  117. clankit-0.1.0/src/clankit/web/guard.py +149 -0
  118. clankit-0.1.0/src/clankit/web/markdown.py +106 -0
  119. clankit-0.1.0/src/clankit/web/payloads.py +195 -0
  120. clankit-0.1.0/src/clankit/web/server.py +174 -0
  121. clankit-0.1.0/src/clankit/web/sessions.py +224 -0
  122. clankit-0.1.0/src/clankit/web/static/api.js +39 -0
  123. clankit-0.1.0/src/clankit/web/static/app.css +1522 -0
  124. clankit-0.1.0/src/clankit/web/static/app.js +521 -0
  125. clankit-0.1.0/src/clankit/web/static/chrome.js +121 -0
  126. clankit-0.1.0/src/clankit/web/static/composer.js +190 -0
  127. clankit-0.1.0/src/clankit/web/static/dom.js +77 -0
  128. clankit-0.1.0/src/clankit/web/static/format.js +79 -0
  129. clankit-0.1.0/src/clankit/web/static/panels.js +146 -0
  130. clankit-0.1.0/src/clankit/web/static/popup.js +219 -0
  131. clankit-0.1.0/src/clankit/web/static/settings.js +608 -0
  132. clankit-0.1.0/src/clankit/web/static/store.js +310 -0
  133. clankit-0.1.0/src/clankit/web/static/transcript.js +343 -0
  134. clankit-0.1.0/src/clankit/web/static/tree.js +256 -0
  135. clankit-0.1.0/src/clankit/web/stream.py +292 -0
  136. clankit-0.1.0/src/clankit/web/templates/index.jinja2 +39 -0
  137. clankit-0.1.0/src/clankit/web/views.py +537 -0
  138. clankit-0.1.0/tests/conftest.py +76 -0
  139. clankit-0.1.0/tests/test_agent_loop.py +402 -0
  140. clankit-0.1.0/tests/test_anthropic_provider.py +1555 -0
  141. clankit-0.1.0/tests/test_cli.py +115 -0
  142. clankit-0.1.0/tests/test_config_actions.py +134 -0
  143. clankit-0.1.0/tests/test_demo.py +93 -0
  144. clankit-0.1.0/tests/test_openai_compat.py +1532 -0
  145. clankit-0.1.0/tests/test_openai_compat_arguments.py +110 -0
  146. clankit-0.1.0/tests/test_openai_compat_errors.py +333 -0
  147. clankit-0.1.0/tests/test_openai_compat_models.py +123 -0
  148. clankit-0.1.0/tests/test_openai_compat_text_tools.py +313 -0
  149. clankit-0.1.0/tests/test_orch_architect.py +584 -0
  150. clankit-0.1.0/tests/test_orch_best_of_n.py +613 -0
  151. clankit-0.1.0/tests/test_orch_common.py +159 -0
  152. clankit-0.1.0/tests/test_orch_escalate.py +575 -0
  153. clankit-0.1.0/tests/test_orch_review_loop.py +548 -0
  154. clankit-0.1.0/tests/test_orch_test_loop.py +818 -0
  155. clankit-0.1.0/tests/test_orch_worktree.py +335 -0
  156. clankit-0.1.0/tests/test_prompts.py +89 -0
  157. clankit-0.1.0/tests/test_session.py +355 -0
  158. clankit-0.1.0/tests/test_skills_evidence.py +263 -0
  159. clankit-0.1.0/tests/test_skills_forge.py +1115 -0
  160. clankit-0.1.0/tests/test_skills_library.py +701 -0
  161. clankit-0.1.0/tests/test_skills_safety.py +213 -0
  162. clankit-0.1.0/tests/test_skills_tool.py +224 -0
  163. clankit-0.1.0/tests/test_task_tree.py +596 -0
  164. clankit-0.1.0/tests/test_themes.py +822 -0
  165. clankit-0.1.0/tests/test_themes_colour.py +131 -0
  166. clankit-0.1.0/tests/test_themes_syntax.py +229 -0
  167. clankit-0.1.0/tests/test_themes_textual.py +309 -0
  168. clankit-0.1.0/tests/test_themes_web.py +159 -0
  169. clankit-0.1.0/tests/test_tools_files.py +1110 -0
  170. clankit-0.1.0/tests/test_tools_search.py +628 -0
  171. clankit-0.1.0/tests/test_tui_commands.py +203 -0
  172. clankit-0.1.0/tests/test_tui_lint.py +134 -0
  173. clankit-0.1.0/tests/test_tui_main.py +341 -0
  174. clankit-0.1.0/tests/test_tui_settings.py +303 -0
  175. clankit-0.1.0/tests/test_tui_support.py +116 -0
  176. clankit-0.1.0/tests/test_tui_units.py +284 -0
  177. clankit-0.1.0/tests/test_ultra.py +327 -0
  178. clankit-0.1.0/tests/test_web_api.py +577 -0
  179. clankit-0.1.0/tests/test_web_demo.py +81 -0
  180. clankit-0.1.0/tests/test_web_security.py +199 -0
  181. clankit-0.1.0/tests/test_web_server.py +123 -0
  182. clankit-0.1.0/tests/test_web_stream.py +382 -0
  183. clankit-0.1.0/tests/test_web_support.py +155 -0
  184. clankit-0.1.0/tests/test_workflow_engine.py +808 -0
  185. clankit-0.1.0/tests/test_workflow_patterns.py +386 -0
  186. clankit-0.1.0/tests/test_workflow_saved.py +141 -0
  187. clankit-0.1.0/tests/test_workflow_script.py +177 -0
  188. clankit-0.1.0/uv.lock +1251 -0
@@ -0,0 +1,7 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ .pytest_cache/
5
+ .ruff_cache/
6
+ dist/
7
+ *.egg-info/
clankit-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,347 @@
1
+ Metadata-Version: 2.5
2
+ Name: clankit
3
+ Version: 0.1.0
4
+ Summary: A coding agent that grows a task tree. Terminal and web UIs, any model.
5
+ Requires-Python: >=3.12
6
+ Requires-Dist: anthropic>=2.10
7
+ Requires-Dist: httpx2>=2.16
8
+ Requires-Dist: jsonschema>=4.23
9
+ Requires-Dist: kdlquery==1.7.0
10
+ Requires-Dist: markdown-it-py>=4.0
11
+ Requires-Dist: openai>=3.55
12
+ Requires-Dist: pygments>=2.19
13
+ Requires-Dist: pyramid-jinja2>=2.10
14
+ Requires-Dist: pyramid>=2.1
15
+ Requires-Dist: pyyaml>=6.0
16
+ Requires-Dist: textual>=8.2
17
+ Requires-Dist: waitress>=3.0
18
+ Description-Content-Type: text/markdown
19
+
20
+ # Clankit
21
+
22
+ A coding agent that grows a **task tree**. Clankit is a Python (≥ 3.12) agent with a terminal
23
+ UI and a web UI, built so you can point it at any model — Anthropic, DeepSeek, OpenAI-compatible
24
+ servers, and a range of free and local models.
25
+
26
+ **Highlights**
27
+
28
+ - **Recursive Task Tree** (the default orchestration): agents split work into subtasks, each
29
+ running on its own model if you want, while parents review, integrate and verify.
30
+ - **Eight more orchestration strategies** — Solo, Review Loop, Test Loop, Architect-Editor,
31
+ Escalate, Best of N, Ultra, and a model-free Demo — with per-method, user-adjustable settings.
32
+ - **Cross-model delegation**: any subtask or helper role can run on a different provider/model.
33
+ - **Two UIs**: a Textual terminal UI and a Pyramid web UI, both driving the same engine.
34
+ - **Skills**: reusable `SKILL.md` instructions with bundled scripts, plus automatic skill
35
+ generation from the work a session actually did.
36
+ - **KDL configuration** in `~/.config/clankit/config.kdl`, with a permission system, session
37
+ resume, `/undo`, token/cost tracking and 25 built-in colour themes.
38
+
39
+ ---
40
+
41
+ ## Installation
42
+
43
+ Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
44
+
45
+ ```sh
46
+ git clone <this-repo> clankit
47
+ cd clankit
48
+ uv sync # creates .venv and installs the `clankit` command
49
+ uv run clankit --version
50
+ ```
51
+
52
+ `uv sync` installs the `clankit` entry point into the project virtualenv, so you can run
53
+ `uv run clankit` from anywhere in the repo. To install it as a standalone tool, use
54
+ `uv tool install .` from the repo root.
55
+
56
+ ## Getting started
57
+
58
+ On first run Clankit writes a commented starter file at `~/.config/clankit/config.kdl`
59
+ (honouring `XDG_CONFIG_HOME`). Every line in it is switched off with `/-`, so the file reads
60
+ back as the built-in defaults while showing you exactly what to write.
61
+
62
+ The one thing you need is a model. Either set an API key in your environment:
63
+
64
+ ```sh
65
+ export ANTHROPIC_API_KEY=sk-ant-... # or DEEPSEEK_API_KEY, OPENROUTER_API_KEY, etc.
66
+ ```
67
+
68
+ or put it in `config.kdl` (see [Configuration](#configuration)). Then:
69
+
70
+ ```sh
71
+ clankit # open the terminal UI in the current directory
72
+ clankit config # show where config lives and which providers are set up
73
+ clankit --demo # play a scripted session — no model or key needed
74
+ ```
75
+
76
+ ## CLI
77
+
78
+ ```
79
+ clankit terminal UI in the current directory
80
+ clankit web web UI on http://127.0.0.1:8420
81
+ clankit run "prompt" run one prompt with no UI and print the answer
82
+ clankit sessions list stored sessions for this directory
83
+ clankit skills list installed skills
84
+ clankit config show configuration status
85
+ ```
86
+
87
+ Flags shared by the UI/`run` commands:
88
+
89
+ | Flag | Meaning |
90
+ |---|---|
91
+ | `-C, --cwd DIR` | work in `DIR` instead of the current directory |
92
+ | `-m, --model PROVIDER/MODEL` | model for this session |
93
+ | `--method NAME` | orchestration method for this session |
94
+ | `--permission-mode MODE` | `ask` / `accept-edits` / `auto` / `read-only` |
95
+ | `-c, --continue` | continue the most recent session in this directory |
96
+ | `-r, --resume ID` | resume a stored session by id |
97
+ | `--demo` | play a scripted session (no model, no API key) |
98
+
99
+ `clankit web` also takes `--host`, `--port` and `--no-browser`. `clankit run` takes `--json`
100
+ (one JSON object per event) and `-q/--quiet` (print only the final answer), and reads the
101
+ prompt from stdin when it is omitted or `-`.
102
+
103
+ Both UIs share the same `/slash` commands: `/help`, `/model [provider/model]`, `/method
104
+ [name]`, `/effort [low|medium|high|xhigh|max|default]`, `/theme [id]`, `/permissions [mode]`,
105
+ `/settings`, `/skills`, `/skillify`, `/init`, `/undo`, `/compact`, `/context`, `/cost`, `/new`,
106
+ `/resume`, `/quit`.
107
+
108
+ ## Model providers
109
+
110
+ Clankit ships with a catalog of known providers. A known provider needs only an API key; a
111
+ custom one needs `kind` and `base-url` as well.
112
+
113
+ | Provider | Key (env var) | Notes |
114
+ |---|---|---|
115
+ | Anthropic | `ANTHROPIC_API_KEY` | Claude models; the default provider |
116
+ | DeepSeek | `DEEPSEEK_API_KEY` | OpenAI-compatible, very cheap |
117
+ | OpenRouter | `OPENROUTER_API_KEY` | one key for hundreds of models, some free |
118
+ | Google Gemini | `GEMINI_API_KEY` | free tier for the listed models |
119
+ | Groq | `GROQ_API_KEY` | fast open-weight models; free plan |
120
+ | NVIDIA API Catalog | `NVIDIA_API_KEY` | free for development |
121
+ | Z.ai GLM | `ZAI_API_KEY` | Flash models are free |
122
+ | Cloudflare Workers AI | `CLOUDFLARE_API_KEY` | small daily free allocation |
123
+ | Cerebras | `CEREBRAS_API_KEY` | paid (new accounts get a credit) |
124
+ | Ollama / LM Studio / llama.cpp / vLLM | — (keyless) | run on your own machine |
125
+
126
+ **Free models.** OpenRouter serves models whose ids end in `:free` (discovered at runtime,
127
+ since the lineup rotates); Gemini, Groq, NVIDIA and Z.ai have free tiers; and the local
128
+ providers cost nothing but your own hardware. Local providers are *keyless*: because Clankit
129
+ cannot know a local server is running, you switch one on by naming it in the config.
130
+
131
+ **Custom providers.** Any server that speaks the OpenAI chat API works as a provider:
132
+
133
+ ```kdl
134
+ providers {
135
+ my-server {
136
+ kind "openai-compatible"
137
+ base-url "http://localhost:11434/v1"
138
+ keyless #true
139
+ }
140
+ }
141
+ ```
142
+
143
+ (To reach OpenAI itself you'd add `base-url "https://api.openai.com/v1"` and an
144
+ `api-key`/`api-key-env`; it is not a built-in catalog entry.)
145
+
146
+ ## Configuration
147
+
148
+ Config lives at `~/.config/clankit/config.kdl` (KDL v2). Everything is optional: what is
149
+ missing or switched off (`/-`) keeps its default, and Clankit's settings screens edit the file
150
+ in place, leaving your comments and layout alone. A realistic file:
151
+
152
+ ```kdl
153
+ /- kdl-version 2
154
+
155
+ model "anthropic/claude-opus-5-5"
156
+
157
+ roles {
158
+ planner "anthropic/claude-opus-5-5"
159
+ reviewer "deepseek/deepseek-v4-pro"
160
+ }
161
+
162
+ providers {
163
+ anthropic {
164
+ api-key-env "ANTHROPIC_API_KEY"
165
+ }
166
+ deepseek {
167
+ api-key-env "DEEPSEEK_API_KEY"
168
+ }
169
+ openrouter {
170
+ api-key "sk-or-your-key"
171
+ }
172
+ ollama
173
+ }
174
+
175
+ orchestration {
176
+ method "task-tree"
177
+ task-tree {
178
+ max-depth 8
179
+ max-parallel 4
180
+ decomposition "adaptive"
181
+ }
182
+ }
183
+
184
+ agent {
185
+ effort "high"
186
+ max-turns 200
187
+ shell-timeout 120
188
+ }
189
+
190
+ permissions {
191
+ mode "ask"
192
+ allow "shell:git status*"
193
+ allow "edit:docs/**"
194
+ }
195
+
196
+ skills {
197
+ generate "ask"
198
+ }
199
+
200
+ ui {
201
+ theme "dracula"
202
+ }
203
+
204
+ web {
205
+ host "127.0.0.1"
206
+ port 8420
207
+ }
208
+ ```
209
+
210
+ Key reference (all defaults shown):
211
+
212
+ | Section | Keys (default) |
213
+ |---|---|
214
+ | top level | `model "anthropic/claude-opus-5-5"` — the default model, `provider/model` |
215
+ | `roles { }` | `subagent`, `planner`, `reviewer`, `judge`, `utility` — each a `provider/model`; unlisted roles use `model` |
216
+ | `providers { }` | per provider: `kind`, `name`, `api-key`, `api-key-env`, `base-url`, `keyless #false`, `enabled #true`, `concurrency`, plus `model "id" { name, context-window, max-output, tools, free, note, input-price, output-price }` |
217
+ | `orchestration { }` | `method "task-tree"`; each method's options in a block named after it |
218
+ | `agent { }` | `effort ""`, `max-turns 200`, `context-window 128000`, `compact-at 0.8`, `tool-output-limit 30000`, `shell-timeout 120`, `run-budget 1000000` |
219
+ | `permissions { }` | `mode "ask"`, `allow`, `deny` (rules are `category:pattern`) |
220
+ | `skills { }` | `directory ""`, `generate "ask"` (`off` / `ask` / `auto`) |
221
+ | `ui { }` | `theme "ayu-dark"`, `show-thinking #true`, `show-tree #true` |
222
+ | `web { }` | `host "127.0.0.1"`, `port 8420`, `open-browser #true` |
223
+ | `themes { }` | user-defined themes: `base <built-in>` plus token → `#rrggbb` |
224
+
225
+ The five `roles` let an orchestrator put different models on different jobs (e.g. a strong
226
+ planner, a cheap utility model for summaries and skill distillation).
227
+
228
+ ## Orchestration methods
229
+
230
+ `method` picks the orchestrator; pick one with `--method`, `/method`, or `orchestration.method`.
231
+
232
+ | Method | What it does | Use when |
233
+ |---|---|---|
234
+ | `task-tree` | Agents split work into subtasks recursively; each subtask owns files, is accepted by commands the harness runs, and parents review and integrate. | Large tasks with genuinely independent parts. Small tasks cost about the same as Solo. |
235
+ | `solo` | One agent does the whole task in a single conversation, with a self-review of the final diff. | Anything that fits one context window; the fastest and cheapest baseline. |
236
+ | `review-loop` | One agent does the work, then a fresh reviewer with a clean context checks the diff and hands blocking findings back, in rounds. | Changes that will be merged without human review, security-sensitive code. |
237
+ | `test-loop` | A strong agent writes failing tests first; another implements until the harness sees them pass (with an optional debugging agent). | Bug fixes and well-specified features in projects with a runnable test command. |
238
+ | `architect-editor` | A strong "architect" explores and writes a plan; a cheaper "editor" makes the changes and can consult it. | Weak, free or local models doing work beyond them. |
239
+ | `escalate` | Tries a cheap model first and only climbs to stronger ones when the work fails a gate. | Mixed workloads where most requests are easy; saves money. |
240
+ | `best-of-n` | N agents build the change independently in isolated git worktrees; the harness tests them and a selector applies the best. | Hard, valuable changes where a wrong result is expensive. |
241
+ | `ultra` | The agent writes short workflow scripts that fan work out to many agents, verify findings adversarially and combine results. | Broad or high-stakes work: reviews, audits, research. |
242
+ | `demo` | Plays a scripted task-tree session through the normal event path. Calls no model, changes no files. | Trying the interface before any API key is configured. |
243
+
244
+ Per-method settings (stored under `orchestration { <method> { ... } }`):
245
+
246
+ - **task-tree** — `max-depth` 10, `max-nodes` 50, `max-children` 6, `max-parallel` 4,
247
+ `decomposition` `adaptive|eager|minimal`, `cross-model` true, `fix-attempts` 1,
248
+ `redispatch` true, `review` `off|final|branches`.
249
+ - **solo** — `self-review` true.
250
+ - **review-loop** — `max-rounds` 2, `reviewer-model` "", `prefer-other-family` false,
251
+ `check` "", `include-minor` false.
252
+ - **test-loop** — `test-command` "", `test-paths` (default globs), `max-iterations` 5,
253
+ `require-failing-first` true, `debugger-after` 2, `author-model` "".
254
+ - **architect-editor** — `architect-model` "", `editor-model` "", `max-consults` 3,
255
+ `final-check` false.
256
+ - **escalate** — `tiers` "", `check` "", `attempts-per-tier` 1, `reset-between-tiers` false,
257
+ `max-turns-per-tier` 60.
258
+ - **best-of-n** — `n` 3, `check` "", `write-tests` true, `selector-votes` 3, `approach-hints` "".
259
+ - **ultra** — `activation` `always|auto`, `max-concurrent` 6, `max-agents` 60,
260
+ `workflow-budget` 1_500_000, `verify-votes` 3, `large-workflow` 25.
261
+ - **demo** — `speed` 100 (percent; 0 plays instantly).
262
+
263
+ The `model`-typed settings (`reviewer-model`, `author-model`, `architect-model`,
264
+ `editor-model`) take a `provider/model` value; empty means "use the role's model".
265
+
266
+ ## Skills
267
+
268
+ A **skill** is a folder containing a `SKILL.md` file: YAML frontmatter between two `---` lines
269
+ (`name` and `description` are required) followed by Markdown instructions, plus any bundled
270
+ scripts and reference files. Optional frontmatter fields include `when_to_use`, `argument-hint`,
271
+ `disable-model-invocation`, `user-invocable` and `metadata`.
272
+
273
+ ```markdown
274
+ ---
275
+ name: release-notes
276
+ description: Generate release notes for this repository from merged PRs. Use when preparing a release.
277
+ ---
278
+
279
+ Run `scripts/release.py --since <tag>` from the repo root, then edit the output into
280
+ `CHANGELOG.md`. Keep the "### Security" section even when empty.
281
+ ```
282
+
283
+ Skills live in `~/.config/clankit/skills` (your library), and can also be read from
284
+ `<project>/.clankit/skills` and `<project>/.agents/skills` (project skills are listed but not
285
+ loaded until you trust the project). Agents see only each skill's name and description in
286
+ their system prompt; when a task matches, they call the `skill` tool to load the full
287
+ instructions ("progressive disclosure"). Bundled scripts are run with the ordinary shell tool,
288
+ so they pass the same permission checks as any command; `$ARGUMENTS` and
289
+ `${CLANKIT_SKILL_DIR}` are substituted when a skill is loaded.
290
+
291
+ **Automatic generation.** After each completed run, Clankit can distil what the session
292
+ learned into new skills (`skills.generate`: `off` / `ask` / `auto`, default `ask`). The
293
+ pipeline collects evidence from executed work, redacts secrets, has an agent on the cheap
294
+ *utility* model propose candidates, and passes them through deterministic gates (must cite
295
+ session steps, pass a safety scan and a syntax check, and not duplicate an existing skill).
296
+ Proposals wait in `~/.config/clankit/skills/.pending` for your approval; hand-written skills
297
+ are never rewritten. You can also trigger it explicitly with `/skillify`.
298
+
299
+ ## Themes
300
+
301
+ Clankit ships 25 built-in themes, each one colour theme for the terminal, the web UI and
302
+ syntax highlighting: **Ayu Dark** (default), Ayu Mirage, Ayu Light, **Monokai Pro** (and its
303
+ Classic/Machine/Octagon/Ristretto/Spectrum/Light filters), **Dracula**, GitHub Dark/Dimmed/
304
+ Light, Catppuccin Mocha/Latte, Tokyo Night, Gruvbox Dark, Nord, One Dark, Solarized Dark/
305
+ Light, Rosé Pine, Kanagawa and Everforest Dark.
306
+
307
+ Switch with `/theme dracula`, set `ui { theme "dracula" }`, or pick from the settings screen
308
+ (F2). You can define your own in the `themes { }` section, starting from a built-in and
309
+ overriding single colours:
310
+
311
+ ```kdl
312
+ themes {
313
+ my-theme {
314
+ base "ayu-dark"
315
+ accent "#c08040"
316
+ }
317
+ }
318
+ ```
319
+
320
+ ## UIs
321
+
322
+ **Terminal UI** — `clankit` (add `--demo` to explore without a model). Type to send a prompt,
323
+ `/` for commands, `f1` for keys, `f2` for settings, `f3` to review skills; `ctrl+t` toggles the
324
+ task tree, `ctrl+y` answers a pending permission/question, `esc` stops a run.
325
+
326
+ **Web UI** — `clankit web` serves the same interface at `http://127.0.0.1:8420` and prints a
327
+ login link containing a random token (`/?token=...`); keep it private. Use `--host`/`--port` to
328
+ bind elsewhere (only do so if other machines should reach it) and `--no-browser` to stop it
329
+ opening a window.
330
+
331
+ ## Permissions
332
+
333
+ Four modes govern what agents may do without asking: `ask` (confirm edits, shell commands and
334
+ network access), `accept-edits` (stop asking about edits inside the workspace), `auto` (ask
335
+ nothing) and `read-only` (refuse anything that changes state). `allow`/`deny` rules refine the
336
+ mode, written `category:pattern` with shell wildcards (e.g. `shell:git status*`,
337
+ `edit:docs/**`); a deny rule always wins. Rules and the mode can also be set per session with
338
+ `--permission-mode` or `/permissions`.
339
+
340
+ ## Development
341
+
342
+ ```sh
343
+ uv run pytest # test suite (asyncio_mode=auto)
344
+ uv run ruff check # lint (and `uv run ruff format` to format)
345
+ ```
346
+
347
+ The project targets Python 3.12; tests live in `tests/` and lint rules in `pyproject.toml`.
@@ -0,0 +1,29 @@
1
+
2
+ Make a coding agent named `Clankit`, written in python with uv with unit tests written in pytest, and pyramid and textual for UIs.
3
+
4
+ ## Model support
5
+
6
+ Should *at least* support Anthropic's models, DeepSeek and freely available models. Configurable by adding API key.
7
+
8
+ ## UI and visual design
9
+
10
+ It should have both a terminal-ui and a web-ui. Visual design should be minimalist but tasteful, but support different color themes; I really like Ayu Dark -- should also have other favourites like Monokai Pro, Dracula and Github Dark.
11
+
12
+ Avoid sloppy anti-patterns: no rounder corners, 1px borders, gradients, overdone typgraphy.
13
+
14
+ ## Configuration
15
+
16
+ All configuration, including API keys, lives in a well-formated and human-readable KDL Document Language file under `~/.config/clankit/config.kdl`. Configuration may be done from the UI, which updates this file.
17
+
18
+ ## Skills and tooling
19
+
20
+ Should have support for skills in the form of a directory under `~/.config/clankit/skills` with SKILL.md files and tooling scripts, similar to how most coding agents do it. There should also be a feature to automatically generated and supply this skill bank with new skills and tools based on work done in the current session.
21
+
22
+ ## Orchistration
23
+
24
+ Clankit's primary orchitration method is constructing a "Task Tree" with a user-configurable depth-limit; default is 10. The user prompt should be broken down into subtasks, then those subtasks would recursively be broken down into subtasks until an agent is satisfied with the simplicity of the task to stop deploying subagents and become a leaf agent. The leaf agents do the building, the intermediate agents look over its subagents' work, does QA and conflict resolution, then glues it all together into a working result of its task, and the root agent reports back to the user and takes input.
25
+
26
+ Orchistration methods should be configurable, research other methods and add the best ones you find. Something like Claude Code's Ultracode might also be a nice addition. Focus on what has empirically been shown to produce the best results. Publicly available research papers on vibecoding, AI and computational linguistics might give good insight to what works and what doesn't.
27
+
28
+ Clankit should also have cross-model support: an agent can opt to deploy subagents using a different model than itself.
29
+