naudachu
bea3735e47
pull.py's docstring said "the limit is on the write, not on the selection", and the code did the opposite: `list_issues` truncated the payload list to `limit`, and pull.py dropped the closed ones after that. A milestone whose first issues are closed therefore answered `--limit 20` with twelve files, and the only statement about the behavior anywhere was the false one. The limit now counts what the run leaves in the store. `list_issues` takes a `keep` predicate, pages keep arriving until `limit` payloads have satisfied it, and the ones that did not are still returned — they were enumerated, and pull.py still reports them as "N closed, not stored". What `keep` means stays the caller's business; the transport only counts. pull.py hands it `lands_in_store`, which is the same test the walk itself applies: a closed issue counts only when the store already has it, since that one is refreshed rather than dropped. Pagination is the other half, and it cuts both ways. `paginate` is now a thin wrapper over a new `pages` generator, so the page after the one that fills the budget is never requested. In the other direction "fetch until N are kept" is "fetch the whole tracker" on a filter that matches mostly closed issues, so a keep-bounded read scans at most PAGE_SLACK times the pages the limit would need if nothing were dropped, then warns on stderr and returns short. Raising --limit raises that ceiling with it. --deps is outside the count: a dependency is followed because an issue named it. remote.py keeps the old meaning and now says so in as many words — it writes nothing, so there is no write for a limit to bound, and its --limit caps the listing, closed issues included. Same flag, two jobs, documented in both scripts and in the skill's command table. Also refuses `--limit 0` instead of dividing by the page size and raising ZeroDivisionError. tests/test_pull_limit.py stubs the transport with a fake that serves `page=`/`limit=` itself, so the request pattern is observed rather than assumed: exactly N files out of a half-closed selection, the second page fetched and the third not, the scan stopping at the budget with a warning, and remote.py's listing unchanged. 251 tests, no network. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
tea — Claude Code plugin for the Gitea CLI
A Claude Code plugin that gives Claude a reference for the tea CLI and enforces a hard rule: every tea command runs under the login the operator chose, never one Claude picked.
What it ships
| Piece | What it does |
|---|---|
/tea:auth skill |
Prompts you to pick a Gitea login and pins it to the project |
/tea:issue skill |
Issues as units of work — create, read, grep, validate, walk the dependency graph. Entirely offline |
/tea:sync skill |
Moves issues between the local store and Gitea — pull, push, comment |
/tea:use skill |
Tea CLI reference for everything that is not an issue — loads command docs on demand |
tea-runner agent |
Subagent on Haiku that runs the scripts and reports back a receipt — the mechanical half, off your main context |
tea-guard hook |
PreToolUse hook that blocks or rewrites every tea invocation |
The layering
An issue is a unit of work first and a Gitea row second. Those are two layers, and knowledge flows one way:
skills/issue DOMAIN what an issue is: format, validation, dependency graph
▲ offline — no tracker, no network, stdlib only
│ imports
skills/sync BRIDGE md <-> Gitea JSON, then over the wire
▲
│ calls
tea-runner EXECUTION runs the scripts, reports a receipt — no opinions
Delete skills/sync and the domain layer keeps working — issues that live only
on your machine are first-class, not drafts waiting to be uploaded. That is the
point of the split: you can plan, write, validate, and track work without a
tracker, and publish only what you choose to.
Prerequisites
- Claude Code — CLI, desktop app, or IDE extension
- Python 3 — required by the
tea-guardhook (python3must be on$PATH) tea— Gitea's official CLI. Install withbrew install tea(macOS) or from gitea.com/gitea/tea/releases- At least one login configured:
tea logins add(interactive — run it in a terminal, not via Claude)
Installation
This is a Claude Code plugin — install it through the plugin marketplace, not by hand-editing settings.json.
-
Register this repo as a marketplace:
/plugin marketplace add https://git.noodles.cam/claude-skills/tea.gitAlready have a local clone? Point at the directory instead:
/plugin marketplace add /path/to/tea -
Install the plugin:
/plugin install tea@tea
The skills (/tea:auth, /tea:issue, /tea:sync, /tea:use) and the tea-guard hook load immediately. Use /plugin to enable, disable, or update it later.
The marketplace registration is written to
extraKnownMarketplacesand the plugin toenabledPluginsin your settings automatically — you don't edit those by hand. There is no top-level"plugins"settings key; if you've added one from older instructions, remove it.
First use
Run /tea:auth once per project. Claude will list your available Gitea logins and ask you to pick one. The choice is written to .claude/settings.local.json and takes effect immediately — no restart needed.
/tea:auth
After that, just ask Claude to do something with issues or Gitea — it loads the
right skill automatically. /tea:auth is only needed for the tracker side;
/tea:issue works without any login at all.
How the login guard works
Every tea invocation Claude writes must carry the literal placeholder --login "$GITEA_LOGIN". The tea-guard hook intercepts the Bash call before it runs, looks up the pinned login from .claude/settings.local.json, and rewrites the command to use it.
Claude is blocked from:
- running
teawithout--loginat all - naming a login itself (e.g.
--login myaccount) - using any variable other than
$GITEA_LOGIN
This prevents silent fallback to the machine's default login (often a personal account) when working in a project that belongs to a different identity.
tea logins list and tea --version / --help are exempt — they don't touch Gitea data.
The tea-runner agent
The skills carry meaning; the scripts carry work. tea-runner is a subagent on
Haiku that does the second half in its own context and hands back a receipt —
what ran, what it touched, what failed, verbatim.
Delegate a batch: pull a milestone and rebuild the index, push the three
issues you just wrote, bootstrap the label set, post a comment from a file you
prepared. Spawning it for a single pull.py 42 costs more than running the
command yourself; the saving is in the loop, the retry, and reading somebody
else's stderr.
It cannot decide anything. No Edit, no Write, no --force, no closing or
retitling, no raw tea, no pushing beyond the set it was handed. A missing
type, a failed validation, an unpushed dependency come back as a question, not
as a guess. The tea-guard hook applies to it exactly as it does to the main
session — the pinned login is enforced on every call it makes.
Project layout
.claude-plugin/
plugin.json plugin manifest
marketplace.json marketplace catalog (makes `/plugin install` work)
agents/
tea-runner.md subagent (Haiku) that executes the scripts
hooks/
hooks.json registers the PreToolUse hook
tea-guard.sh the guard (Python 3, no deps)
skills/
auth/SKILL.md /tea:auth skill
issue/ /tea:issue — the domain layer, offline
SKILL.md
references/format.md canonical issue format (identity, types, templates)
scripts/ Python 3, stdlib only, no network:
issue.py domain module: slug identity, parse/render,
validation, taxonomy, dependency graph,
body checkboxes
issue_new.py create a local issue from its type template
issue_check.py validate against the format
issue_ac.py list the body's checkboxes; tick one
issue_tree.py draw the dependency graph
issue_index.py rebuild tmp/issues/INDEX.md
sync/ /tea:sync — the bridge to Gitea
SKILL.md
scripts/
map.py md <-> Gitea JSON, pure functions, no I/O
_gitea.py transport: login pin, tea api, pagination, filters
pull.py Gitea -> tmp/issues/
push.py tmp/issues/ -> Gitea, then drops the local file
remote.py discovery listing to stdout
comment.py post or edit a comment
use/ /tea:use — tea CLI reference (non-issue entities)
SKILL.md
references/tea/ command docs
Local issue store
Issues live in tmp/issues/ (gitignore it) as flat markdown with one metadata
field per line — so grep -l 'labels:.*type/bug' tmp/issues/*.md works without
a parser.
An origin: local file is the issue — the store, and the only copy.
Anything with origin: gitea is a working copy of something the tracker
already has, and it is deleted as soon as a push confirms the tracker is up to
date:
- Identity is a slug (
wire-sqlc-appclick.md), never a tracker number. Numbers live in agitea:field. origin: localis a complete state. An issue that never leaves your machine is valid and finished — but it is not permanent: pushing ends it.- A successful push deletes the local file (
--updatetoo) and prints the number and URL it now lives at. Only after a confirmed response: a failed call leaves the file exactly where it was. Get it back withpull.py <n>— same slug, samedepends:, even after a rename in Gitea. - Pulling overwrites the body: a fetch, not a merge. It is also how a pushed issue comes back.
- Nothing tracks drift, and there is no second copy to drift. A file that is still here has not been pushed.