Skip to content

Repository files navigation

English selected, switch to Türkçe

Teknesyum Core

Teknesyum Core

Counts, Shows, And Speaks Once


What It Is

Teknesyum Core is an add-on for Claude Code that keeps long coding sessions on track. It watches how much work a session is doing and shows it on the bottom line of your window. It speaks up only when something needs you: a big change with no plan, a risky command, a job that was dropped, or code that was changed but never run. When a session runs out of room or ends, it writes a short note on where the work stands, so the next session carries on after one word: "continue". On a turn where nothing goes wrong, it adds nothing to what Claude reads, so it costs nothing extra.


Doesn't Claude Code Already Do This?

Partly, yes. Claude Code can already hand work to helper agents, make a plan before it edits, work in a separate copy of the repository, show a status line, and run small scripts of your own at fixed moments (these scripts are called hooks). Core leaves all of that alone and wraps none of it.

What Core adds on top:

  • A note for the next session. The work survives a cut session; the new one reads the note instead of starting over.
  • One reminder at the right moment. When a job grows large and there is no plan, you hear it once, not on every turn.
  • Checks before "done". A reply is held back once if jobs from your message were dropped, or if code was changed and nothing was run.
  • A library you open on request. Expert notes from open-source projects, read only when you ask, never loaded otherwise.

What It Does

Every feature, in plain words. The technical detail of each is in How It Works.

  • Counting and a plan reminder. It counts the files a session changes. When the job gets big and there is no plan file, Claude is told once to write one or say skip.
  • Status line. The bottom line of the window shows files changed, whether a plan exists, whether tests passed, how full the conversation is, and whether a handoff note is waiting.
  • On-screen notices. When Core acts, you see one line such as Teknesyum Core > Denylist Stopped A Command. The line is drawn for you only; Claude never reads it, so it costs nothing.
  • Long-running process watch. Programs a session started that are still running after half an hour are counted on the status line. Nothing is stopped.
  • Endless-wait guard. A command that waits in a loop with no time limit is refused, and Claude is told how to add one. Such a loop could otherwise hang forever.
  • Handoff note. When the conversation fills up or the session ends, Core writes where the work stands. The next session reads it and continues.
  • Chime. A sound when Claude is waiting on you, such as a permission question. Silence for everything else.
  • Library. Start or end a message with ?? or ++ and Core searches a catalog of expert notes from open-source projects, then hands Claude the best few. Nothing is installed.
  • Private shelf. pp opens your own notes instead of the public library, on your own machine only.
  • Agency. aa picks a specialist role, such as a designer or a reviewer, and hands your question to a helper agent playing it.
  • Second opinion. ff sends a question to a stronger model once and keeps its answer in a file.
  • Memory check. mc goes through your past requests and lists what was done, what was not, and what waits on you.
  • Interface check. uc brings the steps for checking a user interface: contrast, layout, the design rules.
  • Clean eye. cc hands a request Claude declined to a fresh agent that never saw the conversation; Claude checks the facts itself first, you do not have to argue the case. Its banner also reminds you that /compact breaks a chain of refusals; a hook cannot run it for you.
  • Now and help. ss says you want something now, while Claude is still working. hh lists every mark with an example.
  • Every job, this turn. A message with several jobs is written down as a checklist. If one is dropped without a reason, the reply is held back once.
  • Messages sent while Claude works. A message you send mid-turn is queued, not lost, and asked for once the current job is done. The Queued banner shows only when two or more wait.
  • Questions while Claude works. A code question you send mid-turn goes to a small, cheap reader that only reads files. Its answer comes back in about a minute, marked as not checked, and Claude keeps working. A question about what Claude is doing right now waits for the job.
  • One list for everything put off. Whatever was postponed goes to one list with a reason. It is shown again until each line is done or explained.
  • Proof before "done". A session that changed code and ran nothing is held once and asked to run it and show the output.
  • Reply language. If you asked for replies in Turkish, a long English reply is held once and asked again in Turkish.
  • Closing summary. A long turn must end with a short summary, what is new to you, and what Claude needs from you.
  • No delete commands handed to you. Claude is not allowed to ask you to run a delete; it moves the files to a trash/ folder itself.
  • Screenshot after interface work. When a screen file was edited, Claude is asked for a screenshot and an outside look before calling it done.
  • Books used. Under a reply you see which notes and skills were really read. If Claude names different ones, you are told.
  • Denylist. Destructive commands, such as deleting outside the project or force-pushing, are refused with one line on what to do instead.
  • Model guard. The cheapest model is not used for helper agents unless you asked for it, and you are told when work goes to a model above the session's own.
  • Rules need a reason. When a new ban is written into a rules file without a source, Claude is asked for the risk and a design answer instead.
  • Bug reports. Say "report this to core" and Claude files a bug log in Core's own repository. Open logs are named at the start of the next request there.
  • Cleanup. Old files in trash/ and tmp/ folders are deleted after a set time, and old Core versions are cleared from the plugin cache.
  • Fresh library. Once a day the library is updated in the background.
  • Tools you run by hand. A map of which file imports which, a number checker for reports, a license and signature writer, a setup script, a health check, a project scan and a release script.
  • Other tools than Claude Code. The same checks run in Cursor's own agent and in Gemini CLI. Codex CLI gets the rules as text.
  • Design and review notes. The library carries shelves for designing an interface and for reviewing one.

What It Does Not Do

  • It does not replace Claude Code's own helpers, plan mode or worktrees; the model still picks those itself.
  • It does not install the library, the agency roles or any skill; they are files read on request.
  • It does not stop long-running programs; it only shows them.
  • It does not make a task cheaper. On a task it costs what plain Claude Code costs.
  • The status line does not show inside the Claude Code extension of Cursor or VS Code.

The Numbers First

We ran the same tasks with plain Claude Code and with Core, and compared what they cost and whether the work got finished.

Every claim below was measured against plain Claude Code on the same seat (sonnet, low effort), clean config, 2026-09-05 and 2026-09-06. Method, tables and raw rows are in bench/rapor.md; the whole bench cost about 40 $.

What was measured Plain Claude Code Core 0.16
Ordinary turn, bytes the hooks write into the context (200 turns) 0 0
Ordinary turn, extra tokens per turn, p50 / p95 - +207 / +427, all cache read, 0.0001 $
Tasks 02-05, median cost, five runs each 0.11-0.39 $ within 3 % or cheaper, all pass
Task 06, four files and ~185 lines, three runs 0.34 $, 3/3 pass 0.37 $, 3/3 pass, hook silent 3/3
The one line the hook speaks, when it speaks - ~450 tokens, 0.0007 $, no extra tool call
Resume: session cut at six turns, next session says "continue" 0/3 finished 3/3 finished; second session 0.33 $ vs 0.11 $
The removed 0.15 machinery put back whole - 4-8x the cost, 7-15 agent calls, same acceptance
Each removed 0.15 part put back alone - inside or above the baseline range, nothing the acceptance could see

The table was measured on Core 0.16.0; the hook surface changed in v0.16.1 and again through v0.24.0 (count.js, handoff.js, mod.js, loop.js), and the table is not re-measured. Since v0.39.0 the Bash, Agent and Stop events each run one node process.

What that says in one breath: on a turn where nothing happens, Core costs nothing. On a task, Core costs what plain Claude Code costs. The one thing it buys is a session that can be cut and picked up again; that is where the money goes, and it goes there because the second session does the work instead of saying "looks fine".

The last two rows are the design proof. The previous version gated multi-agent work behind contracts, roles and tiers. Put back whole, it passed the same tasks at four to eight times the price. Put back one piece at a time, with the decision rule written before the runs, no piece moved the acceptance column and none came back. Section 8 of the report has the rows; the variants live under bench/varyant/ and rerun with one command.


Install

Recommended on Windows: Teknesyum Base.

  1. Download Teknesyum-Base.exe (.sha256) and run it. No admin rights are needed.
  2. Find Teknesyum Core in the list and install it. Base also updates and removes it later.

Base is not code-signed yet, so Windows SmartScreen may warn on first launch: choose More info, then Run anyway. More: Teknesyum Base.

Other platforms, or manually:

Windows - one line

irm https://raw.githubusercontent.com/Teknesyum/Teknesyum-Core/v0.83.0/install.ps1 | iex

macOS / Linux - one line

curl -fsSL https://raw.githubusercontent.com/Teknesyum/Teknesyum-Core/v0.83.0/install.sh | bash

Restart Claude Code afterwards. Hooks reload mid-session; the desktop client does not redraw what they produce until it restarts.

Both one-liners point at a tag, never at main. From v0.24.0 on, every release carries four assets: install.ps1, install.sh, install.ps1.sha256 and install.sh.sha256; each .sha256 file holds <hex> <file>, the sha256sum -c shape.

Needed: Claude Code, git, Node.js.

The installers finish by running setup in your own terminal. Skipped it? Run it yourself:

node ~/.claude/plugins/cache/teknesyum/teknesyum-core/*/scripts/setup.js

Setup writes ~/.claude/teknesyum/config.json and wires the statusline. It applies at the next session start.

Cursor, Gemini, Codex And Other Hosts

Where What works
claude in any editor's terminal, Cursor included Everything. It is plain Claude Code.
Claude Code extension in Cursor or VS Code Plugins and hooks are shared with the CLI; the statusline is not shown there.
Cursor's own agent Denylist, loop bound, count, job and evidence gates (one follow-up each turn), handoff. The banner shows on a denied command. Marks and the job hand-back need a context channel Cursor's prompt hook does not have.
Gemini CLI Everything but the statusline: banner through systemMessage, marks, denylist, gates, handoff. Run live on 0.58.0.
OpenAI Codex CLI Rules only, from adapters/AGENTS.md; its hooks are experimental and absent on Windows (v0.114).

Cursor and Gemini need only Node.js and a copy of Core; Claude Code is not required. Wire from a clone, because the plugin cache path moves on every update:

git clone --depth 1 --branch v0.83.0 https://github.com/Teknesyum/Teknesyum-Core "$HOME/Teknesyum-Core"
node "$HOME/Teknesyum-Core/core/scripts/setup.js" --host cursor

Both lines run as they are in bash and in PowerShell. Use --host gemini for Gemini CLI, and add --remove to take the entries out again. Restart the host afterwards. Then paste the block from adapters/AGENTS.md into the project's AGENTS.md (Cursor) or GEMINI.md (Gemini), so the model knows the job list the gate asks for; that block is the one part that costs tokens, about 150 per turn.

A ready-made prompt for a Cursor user's agent is in docs/kurulum/cursor-prompt.md (Turkish).


How It Works

From here on the language is technical: hook events, context bytes, file paths and switches.

Hooks

The evidence gate below is one of thirteen hook entries. Nine events, eleven files, all under core/hooks/:

flowchart LR
  E["Write / Edit"] --> C{"A code file?"}
  C -->|"prose only"| Q["Stays quiet"]
  C -->|"yes"| T{"Tests run on this tree?"}
  T -->|"yes"| Q
  T -->|"no"| A["Asks once, at the threshold"]
  A --> K{"git commit?"}
  K -->|"yes"| R["Seals the work,<br/>counter reset"]
Loading
Event Hook Says
SessionStart count.js Resume: .claude/handoff.md if one exists; the first open - [ ] step of docs/plan.md if one exists; the open lines of .claude/acik.md on every source, compact included; after a compaction, Reply language: Turkish. when the owner's CLAUDE.md asks for Turkish; once a session, when tools.graphify is set and the repo has 400 or more production files, one line (~400 B) saying graphify may be used for a multi-step structural question; else nothing. Once a day it also starts kutuphane.js fetch all --stale 7 detached in the background, so no shelf is older than a week, and runs the cop.js sweep of week-old state files and old plugin versions; the model sees none of it. Outside a compaction it brings back from teknesyum-private/<project>/durum/ what another machine left there (a pull on startup only); a file changed on both machines stays local and the other copy lands beside it as .onceki
UserPromptSubmit mod.js on the first prompt of a session with no title of its own, the sessionTitle field names it --- <Project> T0 when no T0 holds the project's seat on this machine (a T0 idle for a week gives it up), else --- <Project> <Topic> (the README title, else the repo folder, Sohbet for a scratch chat, up to four content words of the prompt); no context, no tokens; a title set by hand or by /rename stays; "titles": false turns it off; first, in the Core or teknesyum-ui repo, one line naming the open logs under logs/openlogs/ with the order to read, fix and archive them before the request (logs the ledger already names are left out; no open log, no line); library hits on ?? / ++, private books on pp, agency seats on aa, the consult recipe on ff, the memory-check recipe on mc, the UI-check recipe on uc (the ui-denetim.md shelf book, the teknesyum-ui scanner and live contrast snippet), on ss nothing when idle and one line saying the owner wants it now when a turn is running, the list of marks on hh (that list goes to the display channel, not into the context) — the mark is read at the start or at the end of the prompt, and mc at the start counts only alone or before a scope such as 2 hafta; the open lines of .claude/jobs.md (the job list, - [ ] job — reason) and of an old .claude/sonra.md move into the ledger .claude/acik.md and the file moves to trash/, [x] ledger lines are pruned to trash/, and the open ledger lines ride along; a prompt that asks for a Core report (core'a raporla, teknesyum'a bildir, report this to core) gets the log.js write recipe, and one that names the UI plugin (ui'a raporla, teknesyum-ui'ye bildir, report this to ui) gets it with --to ui, so the log lands in the teknesyum-ui repo from any project; a prompt with several items leaves a state marker, and when .claude/jobs.md is missing one line asks for the list before the reply starts; on a background event (a finished task, a CI notice) after a reply that closed with Senden istediklerim and got no answer, one line says not to repeat that heading, its items or Önbilgilendirme; an unmarked prompt sent while a turn is still running (the last reply stopped on a tool call in the last half hour) is written to the ledger as Sıra: …, gets a zero-token Queued banner and one line saying to finish the current job first, and the next Stop asks for it once; a question (a question mark, mı, hangi, nerede and the like) instead gets a Devredildi: … line, a Sent To Reader banner and one line saying to hand it in the background to teknesyum-core:okuyucu, a read-only agent on Haiku, and relay the reply under okuyucu (Haiku), denetlenmedi; the reader hands back with ana ajana what is beyond reading the repository (a decision, an opinion, a change, the work in hand) and the main agent answers it after the job (consult 035, bench §18; off with araya: false); when a recent tool result or user message carries a provider-appended copyright / do-not-reproduce / "automated reminder" (the English boilerplate, not a Teknesyum <system-reminder>), one line marks it as provider noise that does not change the owner's task and a Noise Filtered banner shows on the display channel (it cannot be removed, only flagged; the line also tells the model not to defend an earlier refusal); when the last reply reads as a refusal (Turkish or English wording, RET), one line asks the model to judge the request again and to establish the deciding facts itself instead of asking the owner for reasons, with a Refusal Seen banner; a prompt that asks for the words of a song (a music link with söz / dize / lyrics, or şarkı sözü) gets one line saying to find the source of the words first, since a public-domain poem set to music is not a lyric (Song Words banner), and from the second refusal among the last eight replies it adds that earlier refusals feed the next one and that cc, /compact or a new session breaks the chain (Refusal Chain banner); cc puts the clean-eye recipe into the turn (a fresh subagent gets the bare request and the facts the model verified, never the history; the recipe says to always run it, never to skip it on a guess of the outcome), and a bare cc when RET caught none of the last eight replies writes the missed wording to logs/openlogs/BUG-ret-kalibi-kacirdi.md in the Core repo, so the pattern's misses surface as an open log; else nothing; while background jobs of the session run, one line naming each with its age and last output line, so the agent can say what the owner is waiting on
PostToolUse count.js one line at the threshold, once; when an edit to RULES*, CLAUDE*, AGENTS*, SPEC* or a docs/*karar* / *decision* paper adds a ban (yasak, asla, never, forbidden) with no source (URL, licence, law, date), one line asking for the risk and its design answer instead, with the lines named; else nothing. A shell call sent to the background is filed by bekle.js: an In The Background · <job> band line, and a detached watcher shows a desktop toast every 10 minutes (bekleAra in ~/.claude/teknesyum/config.json, minutes) with the job, its age and last output line, until the completion notice lands in the transcript; no tokens
PostToolUseFailure count.js nothing; files a failed test command
PreToolUse yasak.js a denied command with one line on what to do instead. Deleting inside the project is free; leaving it is not — a delete whose target resolves outside the working directory, or is the root itself, is denied, along with disk writes, history rewrites, repo and release deletion, download-and-run pipes, chmod 777 and killing every process (powering the machine off or restarting it is allowed). A history rewrite or a repo, release or remote-branch delete passes once the owner's last message says yes (evet, onay…, sil…, kaldır…, yes), so the model runs it itself instead of handing over the command; disk writes, root wipes and kills never pass; then, in the same process, the loop gate: one line when a wait loop has no upper bound, or when a wait sleeps in the foreground with a timeout over three minutes; else nothing Opening a repository (gh repo create, gh repo fork, a POST to user/repos or orgs/<name>/repos) is stopped only when the user did not ask for it: a yes in the last prompt, or a request to open a repository in one of the last three prompts (depoyu aç, create a private repo, github'a at), lets it run. In a repo whose teknesyum.json names an asset or a run, gh release create and gh release upload first run base.js check and are stopped with the missing items when it fails
PreToolUse ust.js before start_session or set_session_title, the session naming rule in core/oturum-adlari.md (T0 coordinator, --- <Project> <Job>, children without prefix) goes into the context, paid only on those calls; denies a haiku subagent unless the owner's last message names haiku, pointing to sonnet; at the 16th agent within 15 minutes (the platform caps a session at 20 running at once) an Agent Load banner and one line telling the model to offer moving the rest to side sessions, once per window; a Haiku Is Reading banner with the question when the reader agent (okuyucu) is actually called; one line when the turn hands work to a model above the session's own — the called model and what the work is. The session's own model is read from the tail of the transcript; a same or lower model, a model the call does not name, and a consult already announced at the prompt all stay silent. In the same process it refuses a fable consult that is unarmed, spent, or longer than its path line; an Agent call that goes through opens - [ ] ajan: <description> in .claude/acik.md; nothing reaches the model
PreToolUse dur.js denies SendUserFile for a file that is missing or outside the session folders (the working directory: the pane does not open a sibling folder even when it is listed under additionalDirectories), since the file pane cannot open it. "links": false turns it off.
PreToolUse belge.js runs only on a Read of a .pdf, .docx, .pptx or .xlsx inside the working directory: when markitdown is found (tools.markitdown in ~/.claude/teknesyum/config.json, else PATH) it converts the file once into tmp/belge/ and points the read at that copy. A read with pages keeps the original. Writes nothing into the context
Stop dur.js a reply whose markdown link points to a missing file, or one outside the session folders, is sent back with the list; a reply that draws its own progress bar (an old rule a compact summary can revive) is sent back once with an Old Bar banner, since the statusline draws it from .claude/jobs.md; a reply that declines on copyright grounds without naming a year is sent back once (fact gate): find the author and the death year, give a public-domain work in full, or keep the refusal with those two facts (olgu: false turns it off); the closing gate: a turn of five or more tool calls whose reply has no ## Özet / ## Summary heading is held once and rewritten as ## Ön Özet (only what the in-between messages hold), ## Özet, ### Önbilgilendirme with advice, ## Senden istediklerim; off with "closing": false; the delete gate: a reply whose Senden istediklerim / What I need from you hands the owner a delete command (Remove-Item, rm -r, rmdir, del /s) is held once, asking the model to move the target into a trash/ itself or, if it must go for good, to run it without asking; the interface gate: when this turn edited a .tsx .jsx .vue .svelte .css .scss .less .html .axaml or .xaml file and no screenshot followed the last such edit, the turn is held once and asked for a capture at the smallest size, an outside look by a subagent that did not do the work, and "it works" and "it is usable" as two claims; in a desktop project (src-tauri/, Electron, XAML) a browser screenshot does not count. Off: ui: false. Then, in the same process, when the reply ends with a Kullanılan kitaplar: / Books used: line, it compares that line with the books really read and queues Books Differ · Said … · Read … when they differ; the count Stop work: refreshes the diff, and after agency.js show prints the seat once as a chat line. Then a session that edited files and ran nothing is blocked once; the proof is a hash of the code files the model wrote (prose and the ledger do not count), a turn with no Write or Edit is never asked, and a block is not repeated. Off with evidence: false. A reply of 25 words or more that reads as English while the owner's reply language is Turkish is held once. Off with langCheck: false. Kullanılan kitaplar: yok declares no books. The job gate shares the block: an open line in .claude/jobs.md with no reason, a list-shaped prompt with no list or a shorter list (messages queued while the turn ran each add at least one job), or a reply of 40 characters or less while .claude/acik.md has open lines, holds the turn once. Off with jobs: false
SessionEnd handoff.js nothing; writes the handoff, then copies .claude/acik.md, .claude/handoff.md and logs/openlogs/ to teknesyum-private/<project>/durum/ and commits and pushes that folder in a detached background process
Notification notify.js nothing; rings
MessageDisplay bant.js nothing; draws the queued Teknesyum Core > … lines on screen only, and redraws the ## Ön Özet and ## Özet headings as Özet Bastırılıyor · Ara Özet and Asıl Özet banners. On the last chunk of a message it reads the turn from the transcript and adds Books Used · … under the reply: skills called, files read from the private shelf, the library or a skill folder, and kutuphane.js show slugs; a turn with no book draws nothing, the same list is not drawn twice

Only count.js and mod.js can write into the context, and the test suite checks that they are the only ones. Measured: an ordinary turn 0 bytes, ?? about 1.7 KB, pp about 3.7 KB, aa under 1 KB.

A tenth file, host.js, is not wired into Claude Code at all. Cursor and Gemini call it as host.js <host> <event>; it relays what count.js and mod.js say and nothing else, and the suite checks that too.

A turn, end to end:

sequenceDiagram
  participant You
  participant CC as Claude Code
  participant H as Core hooks
  You->>CC: prompt
  CC->>H: UserPromptSubmit
  H-->>CC: nothing, unless a mark is on the prompt
  CC->>You: model works
  CC->>H: PostToolUse, after every edit
  H-->>H: counts the file, refreshes the statusline
  CC->>H: Stop
  H-->>CC: one line, only at the threshold
  CC->>H: SessionEnd
  H-->>H: writes the handoff
Loading

Count

After every Write, Edit and NotebookEdit the hook records the touched file and asks git how many lines changed. Below the threshold it writes nothing: zero bytes into the context.

The threshold is five files, or a hundred and fifty changed lines in tracked files, or a single file whose path looks risky: migrations/, auth, secur, config, a lock file, .github/, a Dockerfile. Lines in brand-new files are shown but do not count toward the line threshold; a task that writes three fresh files is not a task that needs a plan. When the threshold is crossed and there is no docs/plan.md, one line arrives, once per session:

5 files touched and no plan. Write docs/plan.md or say skip.

That is the whole conversation. The model writes the plan or says skip; the hook never asks again.

Show

The statusline reads the same state: files touched with added and removed lines, whether a plan exists, the tests the session ran and how many failed, the context percentage, a progress bar drawn from .claude/jobs.md (twenty ▰▱ cells, one per 5%; a line may carry (n/m) sub-steps; the time left is measured from the pace since the list first appeared, and left out until something is done), whether a handoff is waiting, open bug logs, and hook errors if any. Test staleness is read from the last edit time in state; git runs at most once every ten seconds. Plain text, no colours or measures invented here.

The desktop app does not draw the statusline, so every edit of .claude/jobs.md also queues the same bar on the band (count.js, PostToolUse), full at the last tick; no tokens.

It also counts processes the session spawned through a shell that have been running for more than thirty minutes: ⏳ 2 processes 40 min. The count is refreshed by a detached process at most once a minute, so the statusline never waits on it, and the chime rings once when the first stale process appears. Nothing is stopped; a ninety-minute job is allowed to take ninety minutes, the line only says it is still there.

Banner

When a hook acts, the user sees one chat line such as Teknesyum Core > Kütüphane Döndü · 3 Kitap Uydu · En Çok Üçü Okunacak, drawn as a block above the reply. The hook queues the line on disk and bant.js draws it through MessageDisplay, which changes only what is shown: the stored message and the model's context stay untouched, so the line costs no tokens. Session start, marks, the threshold, the evidence gate, the denylist, a seat read and the job list each have one.

In Gemini the same line rides systemMessage, which Gemini shows you and never sends the model. In Cursor it appears when a shell command is denied.

Bound

Before every Bash and PowerShell call the hook looks for a wait loop with no upper bound: until or while around a sleep, with no timeout, no counter, no deadline. Such a loop sits forever when what it waits for never comes. The call is denied with one line that says how to bound it; the model picks the bound from the job and runs again. A bounded wait that sleeps in the foreground with a timeout over three minutes is denied too: the owner's messages queue behind it, and one session left a question unanswered for 52 minutes through five ten-minute polls. The model writes the owner one line, then reruns it with run_in_background, and the end of the job wakes it. Nothing is killed, so nothing is lost. Everything else passes without a byte.

Denylist

Before every shell call, destructive commands are denied with one line on what to do instead: a delete that leaves the working directory, disk writes, force pushes and hard resets, repo and release deletion, download-and-run pipes, chmod 777, killing every process (powering the machine off or restarting it is allowed). Deleting inside the project stays free. The exact rules are in the yasak.js row above.

Handoff

When the context passes sixty percent, or when the session ends, .claude/handoff.md is written by the machine. It opens with one rule line - read the task, then the changed files, continue from the first unfinished part, do not redo what the diff already shows - and then carries task, the session's first prompt read from the transcript; changed_files from git diff --stat; tests_run from the commands the hook saw, their exit code and the tree hash of that moment; steer, the last three prompts after the first; and plan if there is one. Two sections are left for the model, decisions and next_action, and one line asks for them at the threshold:

Context 64%. Fill decisions and next_action in .claude/handoff.md.

A regenerated handoff keeps what the model wrote. The next session start says one line, Resume: .claude/handoff.md, and nothing else. When the work is finished, the file goes to trash/.

Chime

A sound when Claude is waiting on you - a permission prompt, a question, a dialog - and silence for everything that does not need you. Off with one setting.

Every Job, This Turn

The model lists the jobs of a prompt in .claude/jobs.md as - [ ] job, ticks each one - [x], and may leave one open only with a reason: - [ ] job — waits on your decision.

Two sessions in one folder do not share that file. The first one to take a prompt owns jobs.md until it closes or six hours pass; any other session is told to write .claude/jobs-<session>.md and is checked only against its own list.

On Stop, dur.js holds the turn once if a line is open with no reason, or if the prompt was a list and no list was written, or listed fewer lines than the prompt had items. A message you send while the model is working counts too: each one is at least one more job, and the hold quotes them back. On the next prompt the open lines move into the ledger and the file moves to trash/. A background task notification is not a prompt and takes nothing away.

A job you put off on purpose goes on the shelf instead. Say "rafta dursun" or "shelve it" and the model writes it to docs/later.md as a ## N. Name heading, with the date, your words and the plan so far, and leaves it alone. While the shelf holds a heading, a closing message (one with a Summary or What I need from you heading) ends with a later.md link and the count, and the statusline shows shelf N. Both are drawn on the display side, so the model reads nothing extra. The heading is deleted when the job starts; a prompt that names a shelved heading gets a one-line reminder to do that. The link is always the last line, also in a one-message reply, and is not added when the model printed one itself. "shelf": false in the settings turns it off.

One Ledger For Everything Put Off

Everything put off goes to .claude/acik.md as - [ ] job — time — reason; there is no sonra.md. The hooks write it: mod.js moves the open lines of jobs.md in, ust.js opens - [ ] ajan: <description> for every Agent call (an unticked one leaves for trash/ after a day), and an old .claude/sonra.md is moved in once and sent to trash/. While a line is open the ledger rides on every prompt and on every SessionStart (startup, resume, compact), at most 12 lines and 600 characters; [x] lines are pruned to trash/acik-<ts>.md. When the ledger shows, tick [x] what you did and give a reason for what you did not; a line never leaves without one. A reply of 40 characters or less with open lines is held once at Stop. An empty ledger costs nothing.

Evidence Before "Done"

A session that edited code and ran nothing is held once at Stop: run it, show the output. Tests, tsc, vite build, cargo check|build|clippy, scan.js, eslint, ruff and dotnet build count as proof. The proof is tied to the code files the model wrote, so a README, note or ledger line written after the run, or a release script that bumps a version does not reopen the gate. It asks once, and a turn with no Write or Edit is never asked; a commit resets the count.

When the owner's CLAUDE.md says "Answer in Turkish", a long reply that reads as English is held once at Stop and asked again in Turkish, and the first context after a compaction carries one line with the reply language. Off with langCheck: false.

Marks

?? ++ library, pp private shelf, aa agency, ff fable consult, cc clean eye, mc memory check, uc UI check, ss now, hh help. Each is read at the start or at the end of the prompt, and hh lists them all with an example. The hh list is drawn on the display channel, so it costs the context nothing and no model decides whether to print it.

A prompt marked ?? or ++ opens the library first. The hooks/mod.js hook runs kutuphane.js find on the words, with no model call, and puts up to eight hits and a three-line rule into that turn's context; the model reads at most three books lean, names the source on one line and works with that expertise. Turkish words are folded and mapped to the English catalog, and matches are whole words. A prompt marked pp opens the private shelf instead: the owner's own books under ~/.claude/teknesyum-private/private/, whole (8 KB cap), announced to the user as Teknesyum Core > Özel Raf Açıldı; the shelf exists only when that mirror's remote is the owner's, so on any other machine pp says so and stops. A prompt marked aa opens the agency: agency.js find on the words, at most three seats and one rule in the context; the model reads the seat lean, hands it with the question to a subagent in Turkish and records the reply under docs/danisma/. An ordinary turn gets nothing from any of them.

flowchart TD
  P["Your prompt"] --> M{"Mark at either end?"}
  M -->|"none"| N["Ordinary turn<br/>nothing is written"]
  M -->|"?? ++"| L["Library<br/>1,968 books, no model call"]
  M -->|"pp"| S["Private shelf<br/>owner's machine only"]
  M -->|"aa"| G["Agency<br/>a seat, handed to a subagent"]
  M -->|"ff"| F["Fable<br/>one consult, filed on disk"]
  M -->|"hh"| H["Lists every mark"]
Loading

One Core, Four Hosts

The same hooks run inside Claude Code, Cursor's own agent and Gemini CLI. core/hooks/host.js is a thin adapter: it turns the host's hook JSON into the Claude shape, calls the same counting, denylist, loop, job and handoff code, and turns the answer back. One repository, one version, one test suite.

flowchart LR
  CC["Claude Code<br/>hooks.json"] --> H["count · mod · yasak<br/>loop · dur · handoff"]
  CU["Cursor agent<br/>~/.cursor/hooks.json"] --> A["host.js<br/>adapter"]
  GE["Gemini CLI<br/>~/.gemini/settings.json"] --> A
  A --> H
  CX["Codex CLI"] -.-> R["adapters/AGENTS.md<br/>rules only"]
Loading

setup.js --host cursor or --host gemini wires only its own entries, keeps everything else in the file, and --remove takes them out again. Codex CLI has no hooks on Windows yet, so it gets the rules as text. Gemini was run live on 0.58.0: a hard reset denied, the banner shown, the job gate holding the turn once (log).

Tools That Only Run When Called

Script What it does
scripts/map.js . Import graph: hubs, cycles, orphans. map.js who <file> says what imports it.
scripts/log.js write A log with a fixed shape into Core's logs/openlogs/: --kind hata (a bug, the default), yontem (a method worth keeping) or teklif (a proposal). A log whose title or symptom names teknesyum-ui or one of its scripts, or one written with --to ui, goes to the teknesyum-ui repo's own logs/openlogs/ instead (found beside Core, or by uiRepo in the config); list shows both folders, archive finds a log in either, route --id X --to ui moves one across. --to base does the same for the Teknesyum-Base repo (beside Core, or baseRepo in the config). In a prompt, "core'a raporla", "ui'a raporla" and "base'e raporla" pick the target; each means this local file, never a GitHub issue, and a sentence that only talks about the phrase ("... dediğimde") is not a report. A log that lands in teknesyum-ui also leaves a - [ ] Logu oku: logs/openlogs/<file> line in that repo's ledger .claude/acik.md, so the UI session sees it on its next prompt; archive ticks the line. A prompt such as core'a raporla or report this to core brings the recipe into that turn only.
scripts/base.js init / check What Teknesyum Base needs from a repo it installs: a .teknesyum/ folder with teknesyum.json, icon.png, shot.jpg and full.jpg. init creates the folder, writes the manifest from the root copy (or a draft), copies the project's PNG icon, and for missing screenshots names the repo's capture script or, when there is none, leaves a line in the ledger. check [--zip Z] fails when one of the four files is missing, when a root teknesyum.json disagrees with the folder's on name, category, asset, method or run, or when run is not inside the release zip (the zip given, or the newest one matching asset). A prompt such as Base'e kurulabilir yap or make it installable from base brings the init recipe into that turn only; the release gate in yasak.js runs check.
scripts/advice.js ask --mod gorus --konu <slug> --girdi <file> numbers a fable consult under docs/danisma/, arms the gate for one call and prints a one-line Agent prompt that points at the file, so the input never enters the context twice; record --mod gorus --ajan <agentId> files the reply with its model, output tokens and seconds read from the agent transcript. list shows the records.
scripts/kutuphane.js The library: shelves cloned outside the project (fetch), a catalog built from front matter or the first heading and paragraph, find <words> scored without a model, show <slug…> --lean capped at three books and 48 KB, record under docs/danisma/, push private commits and pushes the private shelf, stale [days] lists how long ago each shelf was fetched, fetch all --stale 7 updates only the ones older than that with fetch --depth 1 and a reset, so clones stay shallow, and slim shallows and garbage-collects every existing clone once. Thirty-eight shelves ship in core/kutuphane.json (1,968 books; MIT, Apache-2.0, CC0, CC BY-SA 4.0 and one CC BY-NC-SA 4.0; the picks are in docs/kutuphane/; the 2026-09-08 market scan of 1000 repositories, 963 read and 93 marked take, is in docs/kutuphane/piyasa-2026-09-08.md), plus `raf add --kind agents
scripts/agency.js A seat from agency-agents, on demand: now the agency shelf of the library, same commands (find keeps its own scoring, show and record are the library's): find ui picks, show <slug> --lean hands the role to a subagent without its personality and metrics blocks, record files the exchange under docs/danisma/. show leaves a seat mark that the next Stop prints in the chat as Seat: <slug> read, <n> KB; the line never enters the context. Nothing is installed as an agent, so the roster never enters the context.
scripts/manset.js Checks a Markdown report: every number in prose must appear in the same section's table or list.
scripts/gozcu.js A pass-through proxy for measuring: point a session at it with ANTHROPIC_BASE_URL=http://127.0.0.1:8790. Each /messages call adds one line to ~/.claude/teknesyum/gozcu/<day>.jsonl: model, system/tools/messages bytes, a hash of the system and tools prefix (a change means the cache was broken), usage, time to first byte and total time. Headers and message text are never written. --upstream chains it in front of another proxy. Not started by any hook.
scripts/scaffold.js License, signature block, language link: fixed texts the model never types.
scripts/setup.js Machine setup: language, chime, private repository, projects folder. The statusline runs a copy of bridge.js in ~/.claude/teknesyum/, so pruning old plugin versions never breaks it. --host cursor|gemini wires the adapter into that host, --remove takes it out.
scripts/doctor.js Eight checks: node, git, version, hooks, statusline, cache, map, logs. cache compares the repo's hooks, scripts and strings with the installed plugin and names every file that is not live yet.
scripts/scan.js Eight read-only checks on the project itself: license surfaces, plan against the five-file threshold, handoff holes, documents against the version, test script, trash/ references, stray temporary files against tmp/, map. Nothing written, no model, nothing into context; the profile only widens the document set.
scripts/hatirla.js Memory check: topla [--gun N] writes every past request, whole, with its evidence - the closing reply, the commits made before the next request, the open job lines of trash/jobs-*, .claude/jobs.md and docs/plan.md - into pages of about 40k characters under tmp/gecmis-N.md, newest first, a repeated request kept once. The whole commit list of the period goes to tmp/gecmis-commitler.md. It prints only an index; every page goes to sonnet by path, in parallel groups of four with one merger. Each request is split into its asks and each ask is checked against the closings and commits of that and every later request. record --ajan <agentId> files the report as tmp/hatirlatici.md - per request what I said, then [x] done, [ ] not done, [!] awaiting decision, [?] unclear - and puts everything not fully done on screen at no token cost; a second record replaces the first on screen. Temporary files live in tmp/, which stays out of git.
scripts/cop.js Measures <project>/trash and the tmp/ files older than a day: node cop.js . prints the total and the ten largest files, exits 1 over 100 MB; --hepsi [root] does it for every project under projectsRoot, largest first. At Stop, at most once an hour, count.js cleans every project under projectsRoot (this one alone without it) by itself: a trash/ entry is deleted a week after it was first seen there, a tmp/ file once it is a day old, and the banner under the finished reply names what went, at zero tokens. --sil empties the trash and the old tmp files now, for good, because the recycle bin frees no space; fresh tmp files stay. Once a day at session start it also sweeps state, banner and advice files older than seven days from ~/.claude/teknesyum/ (never the live session's) and moves all but the newest two Teknesyum plugin versions from the plugin cache to ~/.claude/teknesyum/trash/plugin-cache/, keeping the installed one.
scripts/release.js Bumps the version from the notes left in .changes/, rewrites the install lines, tags; publish creates the GitHub release titled vX.Y.Z and uploads both installers with their .sha256 files, then updates the plugin on this machine (claude plugin update teknesyum-core@teknesyum) so the hooks that run are the ones just shipped; --no-install skips it. Before cut, when betterleaks is found (the tools.betterleaks path in ~/.claude/teknesyum/config.json, else PATH), it scans the commits since the last tag and stops on a finding; --no-secrets skips it.

Settings

Feature Ordinary turn When it acts Off with
Banner 0 tokens 0 tokens, screen only -
Job gate 0 bytes one block at Stop jobs: false
Job hand-back 0 bytes the open lines move to the ledger jobs: false
Mid-work question 0 bytes a question sent mid-turn goes to the Haiku reader, which hands back what is beyond it araya: false
Fact gate 0 bytes a copyright refusal that names no year is sent back once for the author and the death year olgu: false
Ledger 0 bytes when empty at most 600 characters per prompt while a line is open jobs: false
Evidence gate 0 bytes one block at Stop evidence: false
Reply language 0 bytes one block at Stop, one line after a compaction langCheck: false
Denylist 0 bytes one reason per denied command -
Host adapters 0 bytes the same as in Claude Code setup.js --host <h> --remove

The switches live in ~/.claude/teknesyum/config.json. The closing gate is off with "closing": false and the interface gate with ui: false.

The Rule For CLAUDE.md

The plugin does not tell the model how to work. This is the five-line rule it suggests you put in your own CLAUDE.md; the count hook is its only enforcement, and the rule itself is the ~200 tokens per turn in the table above.

- One file and a job you know: do it.
- Five or more files: docs/plan.md first.
- A library you do not know: read before writing.
- When done, run it and show the output.
- Small job: none of the above.

The longer form, with the job list and the handoff, is in adapters/AGENTS.md.

What It Looks Like In Use

Teknesyum ▸ my-app · context 41% · 3 files +82-14 · no plan · tests pass
Teknesyum ▸ my-app · context 67% · 6 files +240-31 · plan · tests stale · handoff

The first line is a session below every threshold: nothing has been said to the model. The second is a session that wrote its plan, ran its tests, edited since (so the last record is stale), and has a handoff waiting for the decisions and next_action lines. The test word is the last record only: pass or fail from the exit code, unknown when the run printed nothing, stale when HEAD or the working tree moved after it.

The Scan

We did not guess what belonged in here. We read the market.

Repositories looked at 1,000
Read end to end, by 45 Opus agents 963
Taken into the library 93
Kept as an idea note, not shipped 165
Declined 705
Shelves shipping today 38
Books in the catalog 1,968

None of them is installed. The catalog is a file on disk, searched without a model, and no shelf ever enters an ordinary turn's context.

Why Big Tools Were Not Bundled

Every one of these was read. None was rejected for being bad; each was rejected for what it costs on a turn where nothing happens.

Tool Why it is not in here
Obsidian A whole note vault beside the repo. What we needed from it was one handoff file, and that is handoff.js.
graphify Excellent on a large codebase, and we still recommend it. It indexes; we did not want an index in every session, so map.js runs only when called.
Context7 Live documentation on demand. It is a per-turn context cost by design; our rule is that an ordinary turn costs nothing extra.
superpowers The broadest skill framework there is. Its own lab shelf is in our library; the framework itself keeps a schema in context every session, which is the one thing we do not do.

The line between class Z and class C is the whole plugin: Z writes nothing ever, A writes only when you call it, B keeps a schema per session, C pays on every turn. Core ships Z and A. Nothing above them.

flowchart LR
  Z["Class Z<br/>writes nothing"] --> A["Class A<br/>only when called"]
  A --> B["Class B<br/>schema per session"]
  B --> C["Class C<br/>pays every turn"]
  Z:::in
  A:::in
  B:::out
  C:::out
  classDef in fill:#1b5e20,stroke:#2e7d32,color:#fff
  classDef out fill:#4e342e,stroke:#6d4c41,color:#fff
Loading

Green is what Core ships. Brown is what it refused.

Design And UI Review

Design work and design review are two different jobs, so the library carries both. Five shelves were added for them after a second sweep of the market.

Shelf What it is for
ui-ux-pro-max Designing: 67 styles, 96 palettes, 57 font pairings, across 13 stacks.
anthropic-skills Designing: frontend-design, brand-guidelines, canvas-design, from Anthropic's own repository.
addyosmani-skills Both: frontend-ui-engineering builds accessible, responsive UI; the accessibility checklist reviews it.
react-best-practices Reviewing: web-design-guidelines reads finished UI code against the Web Interface Guidelines.
pair-design Designing: a framework for working through a design with the user rather than at them.

Alongside what was already there — refactoring-ui, web-design, ecc/skills/design-system, ecc/skills/accessibility, the design seats of the agency. Nothing is installed; ?? ui or ?? arayüzü denetle finds them, and an ordinary turn sees none of it.

flowchart LR
  D["?? tasarım"] --> DS["ui-ux-pro-max<br/>frontend-design<br/>design-system"]
  R["?? arayüzü denetle"] --> RS["web-design-guidelines<br/>accessibility<br/>ui-finish-gate-reviewer"]
Loading

What Went Out

Version 0.16 is a subtraction release. These left the plugin; the v0.15.0 tag holds every one of them, and bench/varyant/ names the source of each part it measures:

  • the contract machine: contract.js, risk.js, verify-runner.js, the relay handoff.js;
  • nine hooks: autoclose, closure, cue, embed, guard, notice, schema, seal, watch;
  • six role texts, the worker agent, the relay skill, tiers.json.

What replaced them is two hooks, count.js and handoff.js, and the five-line rule above. Agents, worktrees and plan mode are still there; they are Claude Code's own, and the model picks them the way it always did. The removed part was the machine that chose for it.


For Developers

Layout

.claude/
  handoff.md           where the work stands, machine-written, two lines yours
  acik.md              the ledger: open lines put off, machine-written, ticked by the model
  jobs.md              the turn's job list, into the ledger on the next prompt, then trash/
  map.md               import graph
adapters/
  AGENTS.md            the rules as text, for Codex, Cursor and Gemini
docs/
  plan.md              the plan the hook asks for, when it asks
  danisma/             consultation records
bench/
  rapor.md             the report behind the table above
  varyant/             the removed parts, ready to be measured again
~/.claude/teknesyum/
  config.json          your setup
  state-<session>.json the count
  hook-errors.log      what a hook could not do

Tests

npm test

The suite drives the real hooks through a temporary repository: the count stays silent below the threshold and writes zero bytes, speaks once above it, treats a risky path as a reason on its own, and stays quiet when a plan is on disk. The handoff is generated from git, keeps what the model wrote, and is announced on the next start but not after a compaction. Alongside those: the statusline in both languages, the personal-convention gate, the scaffold, the map, the chime, doctor, and the bench's own cost and run helpers.

The gates are driven the same way: the denylist and the loop bound, the evidence gate, the job gate and its hand-back. The host adapters get their own suite, Cursor and Gemini events in and host answers out, and the setup wiring is checked to be idempotent and to leave foreign hooks alone.

Design Notes


Contributing

Open an issue before writing code - it is faster than finding out your patch collided with something. Keep the pull request small; a diff that does one thing gets read the same day, a diff that does five gets read never. A new feature comes with a bench/varyant/ entry and its rows; the table at the top is the bar.

The repository is written in English. Contributions land under AGPL-3.0-or-later, same as everything else here; there is no CLA to sign and no ceremony to perform.

If it saves you time, you can sponsor the work.


Support

The plugin is free and stays free - AGPL, no paid tier, nothing kept back for a version you have to buy. If it saved you a bad merge or an afternoon, sponsoring is one way to say so.

There are free ways to help too: report the bugs you hit, write down the criticism you have, recommend it to a friend.

Support Teknesyum   License AGPL-3.0