# agent-plus

> Drop-in plugins for Claude Code that turn 127-tool-call dances into 1-tool-call answers. Five framework primitives plus a marketplace convention. Stdlib Python, no SDK, no config file, no auth dance. Cuts tokens, kills context bloat, runs 20× faster than the agent's default cold-start dance.

## Install

- [One-line install](https://youragentplus.xyz/install.sh): `curl -fsSL youragentplus.xyz/install.sh | sh` — installs all 5 primitives and chains into the wizard
- [GitHub source](https://github.com/osouthgate/agent-plus): MIT licensed, stdlib Python 3.9+, runs standalone outside Claude Code
- [Manual install via Claude Code](https://github.com/osouthgate/agent-plus#manual-install): `claude plugin marketplace add osouthgate/agent-plus && claude plugin install <name>@agent-plus`

## Five framework primitives

- [agent-plus-meta](https://github.com/osouthgate/agent-plus/tree/main/agent-plus-meta): Workspace bootstrap, env-var readiness, identity cache, marketplace lifecycle. Commands: `init`, `envcheck`, `refresh`, `marketplace install|search|prefer`. The wizard that knows which machine you're on.
- [repo-analyze](https://github.com/osouthgate/agent-plus/tree/main/repo-analyze): Collapses the ~67 grep + ~60 ls cold-start dance for unfamiliar repos into one JSON envelope. Returns languages, frameworks, build tools, deps, entrypoints, README structure. 127 tool calls → 1.
- [diff-summary](https://github.com/osouthgate/agent-plus/tree/main/diff-summary): One-call PR triage. Returns role + risk per file, public-API change detection, test-coverage gaps. Replaces 5–20 manual Read calls per PR review.
- [skill-feedback](https://github.com/osouthgate/agent-plus/tree/main/skill-feedback): Agent self-rates skills after each use. JSONL on disk. `report` aggregates, `submit` files an upstream issue with evidence. Closes the feedback loop on whether skills are working.
- [skill-plus](https://github.com/osouthgate/agent-plus/tree/main/skill-plus): Mines the Claude Code session log for repeated commands, scaffolds a real stdlib-Python skill, audits it, promotes it to your marketplace. Commands: `scan`, `propose`, `scaffold`, `inquire`, `promote`.

## Example: what a scaffolded skill actually looks like

A scaffolded skill is three files in your repo, one of which runs:

```
.claude/skills/railway-logs/
├── SKILL.md          # how the agent discovers the skill
├── bin/railway-logs  # stdlib python, runs deterministically
└── README.md         # auto-generated docs
```

The script body is real stdlib Python. Pre-wired argparse, envelope contract, secret redaction, layered env resolver — about 200 lines you don't write. You fill in the killer-command body. Real example from the `railway-ops` skill in the reference marketplace:

```python
# bin/railway-logs (excerpt)
# Stdlib only. Agent invokes the binary directly. No LLM in the loop.

def parse_log_entries(raw: str) -> list[dict[str, Any]]:
    """Parse `railway logs --json` output. Soft-fails on malformed lines."""
    entries: list[dict[str, Any]] = []
    for raw_line in raw.splitlines():
        line = raw_line.strip()
        if not line:
            continue
        try:
            obj = json.loads(line)
            entries.append(obj if isinstance(obj, dict)
                           else {"message": str(obj), "_non_object": True})
        except json.JSONDecodeError:
            entries.append({"message": line, "_non_json": True})
    return entries
```

Deterministic shape in, deterministic shape out. Same call, same JSON envelope, every session. The agent stops re-discovering what it already discovered last session.

## Marketplace convention

- [osouthgate/agent-plus-skills](https://github.com/osouthgate/agent-plus-skills): Reference marketplace with 10 service wrappers — github-remote, vercel-remote, supabase-remote, railway-ops, linear-remote, openrouter-remote, langfuse-remote, hermes-remote, coolify-remote, hcloud-remote
- [Convention](https://github.com/osouthgate/agent-plus#the-marketplace-convention): `<user>/agent-plus-skills` — anyone can publish their own collection at their GitHub handle. No central registry. Borrowed from Homebrew taps.
- [Trust model](https://github.com/osouthgate/agent-plus#the-marketplace-convention): Install pins the commit SHA. Nothing in the cloned repo runs at install time. First-run review per install. Updates opt-in only. Checksum verification when declared.

## Architecture facts

- Stdlib Python only — zero pip dependencies
- Each plugin is one binary in `bin/<plugin-name>` plus a `SKILL.md` discovery file
- Every binary takes `--non-interactive --auto` for deterministic JSON envelope output (frozen public contract)
- Agent invokes the binary directly — no LLM in the loop, no token cost beyond the call
- Works for Claude Code only (claude.ai web Skills and Cowork are out of scope: no Bash, no filesystem, no plugin loader)

## Voice / philosophy

The framework is opinionated. Five principles drive every plugin in it:

- **Stdlib Python only.** No third-party deps. If a feature needs `pip install`, it doesn't ship.
- **Deterministic.** Same inputs, same JSON envelope, every time. No LLM in the runtime path.
- **Frozen public contracts.** The `--non-interactive --auto` envelope shape doesn't change between minor versions. Agent prompts written once stay correct.
- **Jurisdictional ownership.** Each plugin owns its slice of the agent's surface; collisions are detected and resolved at install time.
- **Discipline as the aesthetic.** The framework refuses to do magic on the user's behalf. It makes the deterministic path fast.

## Status

Pre-1.0. Four primitives (`agent-plus-meta`, `repo-analyze`, `diff-summary`, `skill-feedback`) plus the marketplace lifecycle have been dogfooded for months. `skill-plus` is newer (0.4.0). Cold-start orientation and diff triage are production-stable.

## Optional

- [90-second tour](https://github.com/osouthgate/agent-plus#a-90-second-tour): Walk-through of all five primitives in real terminal output
- [Before/after table](https://github.com/osouthgate/agent-plus#before--after): Concrete comparisons of agent-plus vs the default Claude Code dance
- [CONTRIBUTING.md](https://github.com/osouthgate/agent-plus/blob/main/CONTRIBUTING.md): Architecture, conventions, the seven patterns, the envelope contract