redis-companion
A Claude Code plugin for scoping a backend service's Redis access to the minimum permissions it actually needs. Reads the service code, infers the access patterns, and generates a version-aware ACL rule with per-term annotations. Outputs both a concise prompt-ready summary and a full markdown artifact for review. Apply the rule with one shell command.
What it does
You point it at a backend service's directory. It detects the Redis client library, infers the access patterns (keys, channels, streams, commands), asks you two targeted questions (target edition and version — plus an optional follow-up if it finds a TODO hinting at planned commands), and emits a Redis ACL rule that grants only what the service actually needs.
For Redis OSS, it emits a full ACL SETUSER command ready to paste into redis-cli. For Redis Enterprise and Redis Cloud, it emits just the ACL Rule body — paste into the admin UI or REST API.
Who it's for
Backend engineers scoping their service's Redis access to the minimum necessary permissions — new or existing services, in any backend language. The pain is well-known:
- Redis ACL syntax is powerful but cryptic. Translating "this service reads from
cache:user:*, publishes to notifications, and writes a stream" into a correct ACL DSL is a real cognitive load.
- Rules drift between Redis 6 / 7 / 8 —
@scripting was split out of @write in 7, module commands joined @read/@write in 8, pub/sub default-deny flipped on.
- Neither Redis OSS nor Redis Enterprise has a low-friction interface for constructing custom ACL rules from intent. Developers ship with the
default user because the alternative is too much work.
This plugin grew out of Redis ACL Builder — a manual GUI tool built to address the same problem. redis-companion takes the next step: instead of helping you construct a rule by hand, it reads your code and derives the intent automatically.
Install in under 5 minutes
You need Claude Code installed and authenticated.
Option A — Marketplace install (recommended)
In any Claude Code session:
- Open
/plugins
- Add marketplace → paste
mjtrapani/redis-companion
- Install redis-companion
- Restart Claude Code
The plugin is now available in every session, no flags needed.
Option B — Local load (dev / one-off)
git clone https://github.com/mjtrapani/redis-companion.git
cd redis-companion
claude --plugin-dir .
To verify either install, run /agents in the Claude Code prompt — you should see acl-generator in the list.
You can also confirm the knowledge-base skill is active by asking something Redis-adjacent, like "what does +@read grant in Redis 7?" — the acl-reference skill should auto-load (you won't see it in the slash menu by design — it's a model-invocable knowledge base, not an action command) and inform Claude's answer.
Try it on the sample service
A ~40-line sample service is included at examples/sample-service/. It uses redis-py and exercises strings (SET/GET/MGET/SETEX), pub/sub (PUBLISH), and streams (XADD). Run python3 examples/sample-service/service.py directly to exercise every function once with sample data — the file is both the library AND its own smoke test (see the if __name__ == "__main__": block).
Generate the rule
In Claude Code, in the project root:
/redis-companion:rule examples/sample-service
The plugin will:
- Detect
redis-py from the imports + requirements.txt
- Find the key patterns (
cache:user:*, session:*), the stream key (activity:events), and the pub/sub channel (notifications)
- Inventory the commands:
SET, GET, MGET, SETEX, PUBLISH, XADD
- Ask you 2–3 questions: target Redis edition, version (confirms from
INFO SERVER when MCP is connected), and (if a TODO is detected near Redis calls) a question about whether to pre-emptively grant the planned commands
- Write
./acl-rule-sample-service.md to your cwd — comprehensive output with annotations, detected context, and four apply patterns
- Emit a short summary in Claude Code with the rule, the file path, and the apply commands
You can also invoke conversationally:
scope a Redis ACL for examples/sample-service
Apply and validate end-to-end
The strongest validation: apply the rule and watch the service still work under it.
# 1. Apply the rule (inline-sed swaps the placeholder for nopass for local-dev)
sed 's/><changeme>/nopass/' ./acl-rule-sample-service.md | grep -m1 '^ACL SETUSER' | redis-cli
# 2. Verify the rule landed
redis-cli ACL GETUSER sample-service
# 3. Run the service under the locked-down user — should print 6/6 OK
REDIS_URL='redis://sample-service@localhost:6379' python3 examples/sample-service/service.py
