Recall this project's memory, check its health, and review the current diff — from inside a session.

version
1.6.0
GitHub stars
10

Install

/plugin install claudectl@archeus

Run it inside Claude Code after adding the marketplace with /plugin marketplace add babarmuhammad/claudectl.

Contents

Discovered from source

Skills 8

Changelog writer

Maintain a human-readable changelog that tells users what changed.

Steps

  1. Read the existing CHANGELOG.md (follow its style) or start one in Keep a Changelog format.
  2. Gather changes since the last release (git log <last-tag>..HEAD, merged PRs).
  3. Group under an ## [Unreleased] (or new version) heading using these sections, omitting empty ones: Added, Changed, Deprecated, Removed, Fixed, Security.
  4. Write each entry from the user's point of view — the effect, not the commit text — one line each.
  5. On release, rename Unreleased to ## [x.y.z] - YYYY-MM-DD and bump per semver.

Rules

  • User-facing impact only; skip internal refactors and test-only changes unless they affect users.
  • Link issues/PRs where it helps.
  • Newest version on top; keep entries terse and parallel in phrasing.

Code explainer

Explain code so a competent engineer new to it can build a correct mental model.

Steps

  1. Start with the purpose: what this code is for, in one sentence.
  2. Trace the main path: inputs → key steps → outputs, naming the functions/files (path:line) involved.
  3. Surface the non-obvious: invariants, side effects, error handling, concurrency, and any surprising decisions or gotchas.
  4. Note how it connects to the rest of the system (callers, data it touches).
  5. End with anything that looks risky, dead, or worth revisiting — but keep speculation labeled.

Rules

  • Explain the why, not just the what; restating the code line-by-line adds no value.
  • Use the code's real names and cite locations so claims are checkable.
  • Say "I'm not sure" rather than guessing at behavior you can't see.
  • Match depth to the question — a one-liner deserves a one-paragraph answer.

Commit message writer

Write a commit message that explains what changed and why, from the staged diff.

Steps

  1. Inspect the staged changes (git diff --staged). If nothing is staged, say so and stop.
  2. Pick a type: feat, fix, docs, refactor, test, perf, build, ci, or chore.
  3. Write the subject: type(scope): summary — imperative mood, ≤ 72 chars, no trailing period.
  4. Add a body only when the change isn't self-evident: what changed, and the reason/impact. Wrap at ~72 cols.
  5. Note breaking changes with a BREAKING CHANGE: footer.

Rules

  • Describe intent, not the mechanical diff ("prevent double-submit", not "add if-check").
  • One logical change per commit — if the diff spans unrelated concerns, suggest splitting.
  • Never invent changes you can't see in the diff.

Pull-request description writer

Summarize a branch's changes so a reviewer understands them fast.

Steps

  1. Compare the branch to its base (git diff <base>...HEAD, git log <base>..HEAD).

  2. Write a title: type: concise outcome (imperative, ≤ 70 chars).

  3. Fill this structure:

    ## What
    <1-3 sentences: the change and its purpose>
    
    ## Why
    <the problem / motivation, link issues if known>
    
    ## How
    <key implementation decisions a reviewer should notice>
    
    ## Testing
    <what you ran / added; how to verify>
    
    ## Risk
    <blast radius, migrations, rollback — or "low, isolated">
    

Rules

  • Lead with impact, not a file-by-file list.
  • Call out anything needing reviewer attention (schema changes, config, security).
  • Omit a section only when it's genuinely empty; never pad.

Refactor planner

Plan a refactor so behavior is preserved and the change is reviewable.

Steps

  1. State the goal and the behavior contract that must not change (public API, outputs, side effects).
  2. Map what's affected: the target code, its callers, and its tests.
  3. Confirm a safety net exists — the tests that cover current behavior. If coverage is thin, add characterization tests before refactoring.
  4. Break the work into small, independently verifiable steps, each keeping the suite green.
  5. List risks & rollback: what could break, how you'd notice, how to revert.
  6. Present the plan and get agreement before touching code.

Rules

  • Refactor means "same behavior, better structure" — never mix in feature changes.
  • Prefer many small commits over one large one.
  • If a step can't be verified, it's too big — split it.
  • Stop and re-plan if reality diverges from the plan.

Security review

Review changes for security problems that matter, and propose fixes.

Check for

  • Injection: SQL/shell/command/path built from untrusted input without parameterization or escaping.
  • AuthN/AuthZ: missing checks, privilege escalation, IDOR (acting on objects the caller doesn't own).
  • Secrets: hardcoded keys/tokens/passwords; secrets logged or committed.
  • Input validation: unvalidated size/type/range; unsafe deserialization.
  • Crypto: weak/rolled-your-own algorithms, static IVs, predictable randomness.
  • Web: XSS (unescaped output), CSRF, open redirects, permissive CORS.
  • Dependencies & config: known-vulnerable versions, debug/verbose errors leaking internals.

Output

For each finding: severity (critical/high/medium/low), location (file:line), the concrete exploit (inputs → impact), and a specific fix.

Rules

  • Report only issues you can substantiate from the code — no generic checklists, no speculation dressed as fact.
  • Rank by real-world exploitability, not theoretical purity.
  • If you find nothing solid, say so plainly.

Test writer

Add tests that pin down behavior and would fail if the code regressed.

Steps

  1. Detect the test framework and layout already in the repo (pytest, jest, go test, etc.) — match it exactly. Never introduce a new framework.
  2. Identify the unit under test and its meaningful behaviors, edge cases, and error paths.
  3. Write tests that:
    • name the behavior (test_rejects_expired_token), not the function;
    • use the Arrange-Act-Assert shape;
    • cover the happy path, boundaries, and at least one failure mode;
    • avoid asserting on incidental implementation details.
  4. Reuse existing fixtures/helpers instead of duplicating setup.
  5. Run the suite and confirm the new tests pass (and fail when the behavior is broken).

Rules

  • A test that can't fail is worthless — assert real outcomes.
  • Keep each test independent and deterministic (no shared mutable state, no real network/clock unless the project already does).
  • Prefer a few sharp tests over many shallow ones.

Token economy

Answer with the fewest tokens that fully do the job. Precision over prose.

Do

  • Lead with the answer or the result; drop preamble ("Sure!", "Great question", "Here's…").
  • Prefer a short list or a single sentence over a paragraph.
  • Show only the code that changed, not whole unchanged files.
  • Skip restating the request back to the user.
  • Stop as soon as the task is done — no summaries of what you just did unless asked.

Don't

  • Don't pad with caveats, apologies, or filler.
  • Don't compress away correctness: keep exact identifiers, paths, commands, and numbers verbatim.
  • Don't drop steps the user needs to act — brevity ≠ omission.

Calibrate

Terse for routine/mechanical work. If the task is genuinely complex or safety-relevant, spend the words it needs — economy is the default, not a straitjacket.

Commands 3

Run archeus recall "$ARGUMENTS" with the Bash tool from the project root, and read the result as project context before answering.

archeus recall scores archeus's semantic memory graph for this project against the query and prints only the subgraph that fits a token budget — it is local, needs no model call, and returns in well under a second. If the command is not found, tell the user archeus is not installed (pip install archeus) and continue without it.

If it prints (no relevant project memory) there is simply nothing recorded for this topic yet: say so once, briefly, and carry on. Do not re-run it with different phrasings.

With no arguments, recall against the task the user just described.

Run archeus review $ARGUMENTS with the Bash tool from the project root.

Useful arguments, passed straight through: --staged to review the index instead of the working tree, --branch <base> to review a whole branch against its base, --min-confidence <n> to raise the bar on what is reported.

The reviewer reads this project's learned lessons as conventions, so its findings are about THIS codebase rather than generic advice. Report what it found, grouped by file, most serious first — and when it found nothing, say so in one line rather than inventing something to say. If the command is not found, say archeus is not installed (pip install archeus).

Run archeus workspace status with the Bash tool from the project root and show what it reports.

It prints the state archeus tracks for this workspace: how stale the project memory is, which repositories and worktrees are underneath it, and the health checks that catch the common Claude Code problems (a CLAUDE.md that has grown past its budget, a memory graph that has not been rebuilt since the code moved, directories that no longer exist).

Summarise it — do not paste the whole output back. Lead with anything that needs action, and say plainly when nothing does. If the command is not found, say archeus is not installed (pip install archeus).

Sponsors

Details

Marketplace
babarmuhammad/claudectl
Source
plugin
Category
Productivity

More from babarmuhammad/claudectl

All 2