tuck-bit

Every tool. Right on cue.

Make your AI coding agent more deliberate about context, tools, and verification.

TuckBit is an open-source Agent Skill and optional local tooling for task-aware coding workflows. It guides agents toward the relevant evidence and the necessary checks—without bypassing their own permissions.

Copy the agent install prompt · Install with a command · How it works · Benchmarks

Public developer preview. The portable skill, metadata discovery, reversible installer, deterministic router and offline benchmark harness are available. Real cross-provider activation, live tool interception, and verified token savings are not established. See what's implemented and the public roadmap.

Languages: English · Español · Français · Deutsch · Português · Italiano · Ελληνικά · Türkçe · Русский · العربية · हिन्दी · 日本語 · 한국어 · 简体中文 · 繁體中文

Localization is opt-in and remains a preview; some technical reference content falls back to English. Localization details.

Install with your AI agent (no CLI required)

New to GitHub or terminals? Copy the text below into a coding agent that can access your project files and run commands, such as Codex, Claude Code or another compatible agent. It should explain what it will do and ask for permission before making changes.

Help me install TuckBit as an optional Agent Skill in my CURRENT project.
Source: https://github.com/MakeItEzzz555/tuck-bit

1. First inspect TuckBit's README, skills/tuck-bit/SKILL.md and installation/compatibility documentation from this official repository. Do not trust unknown mirrors.
2. Identify which coding-agent host and project skill directory I am using. Prefer a supported, project-scoped installation over a global one.
3. Show me the files and settings you would change, and ask my approval before downloads, dependency installs, file modifications or any other tool commands.
4. Prefer the documented Agent Skills installer when supported (npx skills add MakeItEzzz555/tuck-bit), or the repository's reversible Python installer with a dry run first. If neither is available, explain a manual copy option; do not invent unsupported commands.
5. Preserve existing skills/configurations. Do not overwrite them, install global hooks/MCP servers, enable telemetry, access credentials, or change unrelated projects without specific permission.
6. After approved installation, verify the project-scoped SKILL.md is present. Explain when I can ask the agent to use TuckBit and what remains unverified (installation alone does not prove automatic model activation).

If any step is unsupported or unsafe, stop and explain the alternative rather than guessing.

What this does: asks your own agent to plan and verify installation. Pasting it here does not install anything automatically, and your agent must have appropriate file/tool capabilities. No global configuration changes are authorized by this prompt. Detailed prompt and safety notes.

Install with a command

If you are comfortable with a terminal, first preview the portable skill:

npx skills add MakeItEzzz555/tuck-bit --list

Then install it with the community Agent Skills installer (select the client and scope it supports):

npx skills add MakeItEzzz555/tuck-bit

Installation is distinct from successful model-driven activation. Inspect the source first; don't grant unexpected filesystem, credential or network access. For a dry-run project-scoped Python installer and rollback instructions, see install details and compatibility.

Why TuckBit exists

A simple coding request can become repeated repository scans, entire tool catalogs in context, several agents rereading the same files, or unnecessary test loops. TuckBit's goal is to reduce unproductive work, not required reasoning or checks.

These are design goals and guidance, not measured before/after outcomes. Benchmark methodology · Public example.

How it works

TuckBit's portable skill provides advisory guidance when your host loads it. The optional local router accepts explicitly supplied task data; it does not inspect hidden reasoning, automatically intercept agent calls or grant tool permissions. Single is the default workflow; Parallel, Continuous and Review-only require appropriate scope or consent.

Read the architecture · Agent-specific policies · Security and privacy

The six capabilities

No background service is required for the portable skill. TuckBit does not grant itself access to credentials, private reasoning, or tools the host hasn't authorized.

Developer tooling (optional)

TuckBit's no-model router and profiler require the full repository checkout. They do not silently inspect active global instructions or launch model sessions.

git clone https://github.com/MakeItEzzz555/tuck-bit.git
cd tuck-bit
python3 scripts/tuckbit.py doctor
python3 scripts/workflow_router.py examples/workflow-incident.json

For a project-only installation preview without changing agent settings:

python3 scripts/install.py install --scope project --project /path/to/your-project --client codex --dry-run

Full CLI usage, rollback and tests.

Local capability index and execution profiling

The full source checkout now includes opt-in, read-only metadata discovery and redacted event profiling. The registry indexes only explicitly selected skill roots and optional tool catalogs; it never contacts MCP servers or activates tools. The standalone Agent Skill installation remains instruction-only: root-level Python CLI utilities are not yet bundled into the portable skill package.

# Index this repository's skill and a synthetic, nonsecret tool catalog.
python3 scripts/capability_registry.py build \
  --root skills \
  --tools-file examples/tool-metadata.synthetic.json \
  --output /tmp/tuckbit-preview-index.json

# Find candidates (metadata only), and ensure the snapshot is still fresh.
python3 scripts/capability_registry.py query \
  --snapshot /tmp/tuckbit-preview-index.json \
  --text "Swift regression tests"
python3 scripts/capability_registry.py verify \
  --snapshot /tmp/tuckbit-preview-index.json \
  --root skills --tools-file examples/tool-metadata.synthetic.json

# Supply a catalog and optional redacted observations to the task router.
python3 scripts/workflow_router.py examples/workflow-incident.json \
  --registry-snapshot /tmp/tuckbit-preview-index.json \
  --trace examples/trace-baseline.synthetic.json

A lightweight profiler compares caller-supplied numeric trace summaries without accepting raw prompts, logs, or tool arguments:

python3 scripts/trace_profiler.py compare \
  --baseline examples/trace-baseline.synthetic.json \
  --candidate examples/trace-candidate.synthetic.json

The trace files above are synthetic test fixtures, not real token savings. No user-agent session is queried. See metadata registry and safe telemetry.

Reproducible benchmark bundles (offline harness preview)

TuckBit now includes a no-model, repeated-task harness for testing evaluation infrastructure. It builds a disposable Git fixture, creates a fresh worktree from the same commit for every trial, alternates baseline/treatment order, and reports correctness and operation/time distributions for each task.

python3 scripts/repeat_bundle.py \
  --bundle evals/bundles/offline-v1.json \
  --output /tmp/tuckbit-offline-run.json

The example contains three tasks, four repetitions, two identical Python conditions (24 offline trials). This is not an AI-agent benchmark, and token/cost/human-review metrics are unavailable. The real next step is a consent-based, provider-native repeated-run adapter. See reproducible bundle methodology and the example result.

Agent support

One canonical Agent Skill. Provider-specific policies only where the runtime genuinely differs.

The manifests and local skill discovery are tested, but native inference-driven activation has not been validated across all these clients. Compatibility matrix.

Real-world workflow choices

Locate one behavior, inspect connected contracts, implement the narrowest complete fix, run the focused test, review diff and stop. Don't create a whole team for a one-line change.

Preserve session invariants and rollback options; inspect ownership and data flow; implement incrementally; run required security and regression checks. An execution budget never cancels mandatory verification.

python3 scripts/workflow_router.py examples/workflow-incident.json

Assign separate file ownership, exact deliverables and tests. Workers return evidence rather than full transcripts. The coordinator integrates and validates the result.

python3 scripts/workflow_router.py examples/workflow-parallel.json

Require a genuine trigger, saved checkpoint and explicit authorization. An idle workflow shouldn't burn model turns polling for something to happen.

python3 scripts/workflow_router.py examples/workflow-loop.json

What is actually implemented?

Run all local checks at zero model-token cost:

python3 -m unittest discover -s tests -v
python3 scripts/public_audit.py
python3 scripts/sync_distributions.py --check
python3 scripts/smoke_free.py --interop --claude-validator

The last command may use npm/network for the public skills package; it still launches no language model.

Why this isn't another orchestration framework

TuckBit is designed to work with native agent features instead of wrapping every task in another expensive coordination loop. It's an efficiency policy and capability layer, not a replacement for Codex, Claude, Gemini, or their existing skills.

It deliberately prioritizes:

• Instructions before automation: start from the full prompt and genuine host constraints.
• Useful evidence over broad context: only request more when it changes the answer.
• One capable worker over unnecessary agents: parallelism must justify its coordination overhead.
• Verified quality over vanity metrics: no made-up cost reduction graphs or “10×” claims.
• Reversibility and local privacy: no silent global hooks, credentials indexing or background scraping.

Help build the next version

We'd especially value feedback from people who use Codex, Claude Code, Gemini CLI, Cursor, OpenCode, or Copilot on real repositories.

• Reproducible native skill activation reports using non-sensitive sample projects.
• Public benchmark tasks comparing equivalent correct outcomes.
• Reviews of install/uninstall paths, hook opt-in boundaries and untrusted skill/MCP metadata.
• Provider documentation fixes, regression tests and onboarding improvements.

Report a bug or feature request · Browse issues · Join discussions

For security vulnerabilities, use GitHub private vulnerability reporting rather than a public issue; see SECURITY.md.

Research, architecture and contribution

Privacy · Capability index · Profiler · Provider execution research · Opt-in hook adapters · Task-aware design · Architecture · Roadmap · Security · Tests · Contributing

TuckBit is public and MIT-licensed, but remains an early developer preview. Contributions, issue reports and reproducible experiments are welcome. Please read CONTRIBUTING.md, the public roadmap, and SECURITY.md before sharing logs or code.