veloci 0.3.3

# Veloci Redactor agent skills

These skills make AI coding agents read and search sensitive files through `veloci`. Secrets and personal data are replaced by `[REDACTED-N]` tokens before they reach the model.

| Skill | What it does |
|---|---|
| [`veloci`](skills/veloci/SKILL.md) | Reads protected or sensitive files with `veloci redact`, searches them with `veloci grep`, and edits them without ever writing a `[REDACTED-N]` token back. |
| [`veloci-setup`](skills/veloci-setup/SKILL.md) | On first use in a project, asks which files to protect and records the answer in `veloci.yml`. |
| [`veloci-config`](skills/veloci-config/SKILL.md) | Customizes detection: allow lists, custom patterns, PII, the Privacy Filter model, and the protected files. |
| [`veloci-share`](skills/veloci-share/SKILL.md) | Redacts logs and other output before they go into issues, pull requests, chat or web tools. |

Every skill needs the `veloci` binary on `PATH`. The Claude Code plugin bundles it for macOS, Linux and Windows (x86_64 and arm64). Other agents need it installed:

```console
cargo install veloci-cli
```

## Installing

### Claude Code

```console
/plugin marketplace add phayes/velociredactor
/plugin install veloci@veloci
```

The plugin installs the four skills, a `PreToolUse` hook and the `veloci` binary. Each release attaches the plugin as `veloci-plugin.zip`, and the marketplace installs the latest one. The hook does nothing unless a project turns on `enforce` (see below).

### Other agents

The skills follow the [Agent Skills](https://agentskills.io) standard. Copy the directories under `skills/` into the agent's skills directory:

| Agent | Project | Personal |
|---|---|---|
| Codex, Gemini CLI, GitHub Copilot, Cursor, and most others | `.agents/skills/` | `~/.agents/skills/` |
| Claude Code, without the plugin | `.claude/skills/` | `~/.claude/skills/` |
| Codex | | `~/.codex/skills/` |
| Gemini CLI | `.gemini/skills/` | `~/.gemini/skills/` |
| GitHub Copilot | `.github/skills/` | `~/.copilot/skills/` |

For example, for a single project:

```console
git clone --depth 1 https://github.com/phayes/velociredactor /tmp/veloci
mkdir -p .agents/skills
cp -R /tmp/veloci/plugin/skills/* .agents/skills/
```

Only Claude Code gets the enforcing hook. In other agents the skills work by instruction alone.

## Choosing the protected files

The first time the skills are used in a project, the agent runs `veloci agent status`. If the project hasn't chosen its protected files yet, the agent:

1. finds likely candidates by file name, and files whose contents hold secrets (`veloci scan`, which never shows the values; `agent status --no-scan` skips reading contents);
2. asks you which to protect, what to exclude, and whether to enforce;
3. writes your answer with `veloci agent init`.

The answer lives in the `agent` section of `veloci.yml`. Commit that file, so every teammate and agent shares it:

```yaml
agent:
  protected:
    - ".env*"
    - "*.pem"
    - "secrets/"
  exclude:
    - ".env.example"
  enforce: true
```

Patterns follow `.gitignore` conventions, relative to `veloci.yml`.

## Enforcement

With `enforce: true`, the Claude Code plugin's hook runs `veloci agent hook` before every Read and Grep tool call:

- **Read of a protected file:** denied. The agent is told to run `veloci redact FILE`.
- **Grep of a protected file, or of a directory holding one:** denied. The agent is told the exact `veloci grep` command to run instead. The directory walk follows ripgrep's rules, so files that `.gitignore` excludes don't count, because the Grep tool wouldn't search them either.

Limits:

- Shell commands such as `cat .env` are not intercepted. The skills tell the agent not to run them, but that is an instruction, not a guarantee.
- If `veloci` isn't installed, or the configuration is broken, the hook fails without blocking. It never stops the agent from reading anything at all.

## Developing

```console
claude plugin validate .            # the marketplace, from the repository root
claude plugin validate ./plugin     # the plugin
claude --plugin-dir ./plugin        # try the checkout
```

A checkout has no `libexec/`, so `bin/veloci` falls back to a `veloci` installed elsewhere on `PATH`. Tagged releases build a binary for each target into `libexec/`, stamp the tag's version into `plugin.json` and publish the zip (see `.github/workflows/rust.yml`).