Gustavo.eng.br

The best "undocumented" feature of Claude Plugins

Gustavo Ambrozio — Thu, 30 Oct 2025 00:00:00 GMT

Note

The plugin mentioned below was removed from the repository as there's now a better one. All links still work but they reference the last version before I removed it from the repository.

Getting started with my first plugin

When Anthropic announced Plugins for Claude Code 3 weeks ago, I immediately wanted to create one. Their Skills announcement a week later adding support for them in Plugins sealed the deal.

My own plugin marketplace repository was born from this excitement, along with my first plugin to help with iOS and macOS development. The plugin consisted of some of the MCP servers that I use on all my projects, a simple slash command and, what I was most excited about, a skill to help Claude when dealing with xcodebuild, a notoriously verbose tool that is known to eat a lot of tokens.

There are some MCP servers out there to help with that but they still produce a lot of tokens and every once in a while a project that compiles fine in Xcode will fail to compile using the plugin for no particular reason, sending Claude on a wild ride trying to fix non-existing issues.

A tool called xcsift showed up a few weeks ago. It can parse the verbose output of xcodebuild and swift and output a succinct json that is easier for Claude to parse and very token efficient.

I started using it on some of my projects by adding instructions to my CLAUDE.md files but I decided to integrate it into a skill within this plugin.

Building the Skill

For those unfamiliar: a skill is a set of instructions and supporting files and scripts Claude loads on demand. Sessions start with Claude reading a brief description to determine when to activate the skill, then load full instructions only when needed, saving context.

My skill had what I thought was a simple, straightforward description that I hoped would be enough to make it be used when necessary:

Compiles Xcode projects and swift packages and report errors or warnings. Use it whenever you would use xcodebuild or swift commands.

The rest of the skill instructed Claude to use the included shell script whenever it needed to invoke xcodebuild. The script was simple: it first makes sure xcsift is installed on your machine, installing it if necessary. Then it invokes xcodebuild with all the provided flags and some that I always want to provide.

Testing the skill locally on one of my projects by asking it to make sure the project compiled worked as I expected:

<div style="background: #000; color: #bbb; padding: 1em; border-radius: 8px; border: 5px solid #888; font-family: Monaco, monospace; font-size: 13px; overflow-x: auto;"> > Make sure the project compiles ⏺ I'll build the project to check for any compilation errors. > The "swift-compile" skill is loading ⏺ I'll build the workspace to check for compilation errors. ⏺ Bash(cd /Users/gustavoambrozio/Development/ClaudeCodePlugins/SwiftDevelopment/skills/swift-compile && scripts/xcodebuild.sh -workspace /Users/gustavoambrozio/Develop…) timeout: 5m 0s ⎿ { "status" : "success", "summary" : { … +5 lines (ctrl+o to expand) ⎿ Shell cwd was reset to /Users/gustavoambrozio/Development/MacOSTestProject ⏺ ✅ Project compiles successfully! The build completed with: - 0 errors - 1 warning (minor) - Build status: success The MacOSTestProject workspace is building correctly. The single warning is minor and doesn't prevent compilation. </div>

Good sign. I published and asked my co-workers to test it out.

The feedback was quick and disappointing: Claude was still using xcodebuild directly and that they had to explicitly ask Claude to use the skill.

To try to reproduce the issue I changed my agent to Haiku and turned off thinking mode. This led to Claude ignoring my instructions now.

I sighed and put this aside for a while until something caught my attention.

How a deprecation warning revealed the solution

Later that day I opened Claude Code and saw a note saying that "Output styles are deprecated". This got me upset as this is a feature I cherish (more on that in a future post).

Luckily it provided an alternative in the form of a plugin hook.

Claude shows a link to their Explanatory Output Style Plugin. This plugin is very simple, consisting only of a SessionStart hook that gives initial instructions to Claude Code.

The plugin invokes this simple script when a session starts:

#!/bin/bash

# Output the explanatory mode instructions as additionalContext
# This mimics the deprecated Explanatory output style

cat << 'EOF'
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "You are in 'explanatory' output style mode, where you should provide educational insights about the codebase as you help with the user's task.\n\nYou should be clear and educational, providing helpful explanations while remaining focused on the task. Balance educational content with task completion. When providing insights, you may exceed typical length constraints, but remain focused and relevant.\n\n## Insights\nIn order to encourage learning, before and after writing code, always provide brief educational explanations about implementation choices using (with backticks):\n\"`★ Insight ─────────────────────────────────────`\n[2-3 key educational points]\n`─────────────────────────────────────────────────`\"\n\nThese insights should be included in the conversation, not in the codebase. You should generally focus on interesting insights that are specific to the codebase or the code you just wrote, rather than general programming concepts. Do not wait until the end to provide insights. Provide them as you write code."
  }
}
EOF

exit 0

Turns out plugins DO have a way to provide instructions to the user by using a SessionStart hook. While saying this feature is "undocumented" is not accurate - the documentation for hooks clearly shows that you can do this - I hadn't considered using this in the context of plugins to provide plugin specific instructions.

This led me to create a similar script and added to my plugin's hook configuration. I don't like the way Anthropic embeds their instructions in a heredoc on the shell script so my plugin reads a markdown of the instructions so it's easier to edit them.

And that got me thinking that I could use hooks to make extra sure that Claude would use my scripts to compile code.

Since Claude always sends a PreToolUse hook that you can use to deny the use of a tool I created another script and added to the PreToolUse hook configuration. It checks what command line is being called and if the user is using xcodebuild directly it denies access to the tool and clearly tells Claude to use the skill.

After all this arm twisting I'm pretty confident that Claude will always use my skill to compile my projects. :crossed_fingers:

TL;DR

Plugins are a powerful tool for Claude Code and I think we'll start seeing a lot of very useful ones in the next few weeks, especially when developers start to understand and explore the interactions between all the parts of a plugin. I'm excited to expand this plugin with more tools and create others.

If you have any issues with this plugin or want to improve it in any way, please open an issue or, even better, clone and create a PR.

Open Sourcing the Claude Settings MacOS app

Gustavo Ambrozio — Sun, 23 Nov 2025 00:00:00 GMT

How Claude Code Changed My Workflow

For most of my professional life as a developer I've had ideas of apps I could build to solve particular problems or just improve parts of my life. But almost all of them were just relegated to notes or even just dismissed outright as I knew I didn't have time to work on them.

Then I started using Claude Code and in a few sessions I saw how it could be used to build things much faster than I could, especially for prototypes and experiments where quick iteration mattered more than code quality.

Ideas that had been relegated to notes quickly turned into projects and I soon had a few new folders full of code. I also added Claude to a lot of old projects and even to my note taking folder itself. But this rapid expansion created a new problem.

Managing Claude Code Settings Across Projects

With every project I had a set of MCP servers, slash commands, different authorization settings. Then Anthropic implemented sub-agents, plugins, output styles, skills and before I knew it, I didn't know what I had set up for each project. Copy/pasting of json from one folder to another was a common operation. This manual management was tedious and error-prone, exactly the kind of problem that deserved a better solution.

That's when I decided to create the ClaudeSettings MacOS app to try to make this new problem easier to deal with.

Two weeks after starting the project, it's ready to be released and open sourced. It's mostly built by Claude Code, with some manual refinements here and there. I'm sure there are some edge case bugs out there but it works well enough to make my life a bit easier.

How it helps

One of my main uses of the app is for plugins. When installing a plugin in Claude Code, it defaults to installing it in the global configuration and there's no flag to change this scope (unlike when adding an MCP server). ClaudeSettings makes it easy to move a plugin from the global configuration to a specific project and then copy it only to the projects where you'll actually use it.

I also use it to move settings from settings.local.json to the settings.json file that gets checked into Git. Or to move settings I want on all my projects to the global config. All with just a simple drag and drop.

There are still many improvements to make to the app, like supporting MCP server configurations, slash commands, sub-agents and who knows what else Anthropic will add to Claude Code by next week. Just keeping up with their changelog is almost a full time job.

So if you also have a ton of projects and want to tame your settings, give it a try. The app is open source on GitHub. Contributions and feedback welcome as Claude Code continues to evolve.

Here's a little taste of it:

How I'm still using my Claude subscription for unattended jobs

Gustavo Ambrozio — Mon, 18 May 2026 00:00:00 GMT

Recently Anthropic changed their policy to make using claude -p (the headless / print mode that almost every Claude Code automation I've written depends on) draw from API credits instead of my subscription usage limits. Interactive Claude Code stays on the subscription I already pay for; only -p gets the per-token bill. Needless to say, despite their attempt to make this sound like a good thing, I was not very happy with this change and was not about to give up my VC-backed subsidized tokens just yet. So I started thinking about how I could keep all my automations while still not having to pay this new -p tax.

I was pretty sure I could accomplish the same as -p with an "interactive" session, a few hooks, and some tmux trickery.

After a few attempts I had a Claude Code plugin and a couple of wrapper scripts that drive a normal interactive Claude session as if there were a human at the keyboard.

TL;DR: How can you use this

If all you need is to replace your use of claude -p, then the claude-auto script can probably replace it with no changes. Just download it (and claude-transcript), put them somewhere in your $PATH, and use claude-auto wherever you used claude -p.

For example, one of my scripts was just claude -p --dangerously-skip-permissions "/pr-comment". pr-comment is one of my skills that runs a code review on the current GitHub PR for the branch it is running on and adds comments to it. For this one I replaced it with claude-auto --dangerously-skip-permissions "/pr-comment".

The output changes a bit but, IMHO, in a good way. claude-auto gives you a simple transcript of what Claude did during your session in a way that was hard to get with claude -p. This comes from claude-transcript.

Look at the examples folder for sample scripts - cron, batch, parallel-across-repos, and an attended variant for the rare cases where you do want Claude to be able to ask you a question.

How does it work

A Claude Code plugin is a directory with a collection of hooks, skills, agents, etc. Autonomy is four small hook handlers.

SessionStart: tell Claude to act without user input

One of the main uses of a SessionStart hook is to inject context at the start of a session. Autonomy injects a short prompt to steer Claude into working without user input. By default it assumes nobody is watching:

You are running in fully unattended mode. There is no human available to
answer questions, confirm decisions, or approve plans.

Do NOT use the `AskUserQuestion` tool — it is blocked in this mode and
will return a stock denial telling you to proceed without asking. Do not
enter plan mode to seek approval, and do not stop to request clarification.

When requirements are ambiguous, make a reasonable judgement call based on
the existing code, project conventions, and the task description, then
continue. State any non-obvious assumptions you made in your final output
so they can be reviewed after the session ends.

If you do plan to attach to the tmux session and want to answer the occasional question, set CLAUDE_AUTO_QUESTIONS_OK=1 and Autonomy injects the softer version instead:

You should work as autonomously as possible on this session so there's no
need to get into plan mode to create a plan and ask the user for approval.

If you deem that the work cannot be done without user input then you can
ask questions. Use the `AskUserQuestion` tool for this. But only do this
if it is absolutely necessary, otherwise just do the work without user
input.

PreToolUse: actually blocking questions

The SessionStart prompt is just a hint. Claude sometimes decides this is the absolutely-necessary case and reaches for AskUserQuestion anyway. In an unattended run "you should not ask" needs to become "you cannot ask", otherwise the session sits there forever waiting for an answer that will never come.

The fix is a PreToolUse hook with "matcher": "AskUserQuestion". When the hook prints this JSON to stdout, Claude Code refuses to run the tool and surfaces permissionDecisionReason to the model in place of a result:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "This session is running in autonomous mode, so no human is available to answer. Use your best judgement based on the existing code and the original task description, and continue. State any non-obvious assumptions in your final output for later review."
  }
}

The hook reads CLAUDE_AUTO_QUESTIONS_OK from the environment. If it's 1, the script exits 0 with no output (allow); otherwise it prints the deny JSON. The same env var is what swaps the SessionStart prompt between the two variants above, so the model and the enforcement layer stay consistent.

The default is strict. Autonomy assumes nobody is watching. If you intend to attach to the tmux session and want to be pinged for ambiguous calls, CLAUDE_AUTO_QUESTIONS_OK=1 claude-auto "..." flips both layers to the soft version. examples/attended-run.sh is a thin wrapper that sets it for you.

Stop: when stop doesn't always mean stop

The first version of this hook was dead simple: tmux send-keys /exit. Every time Stop fired, the session ended because I naively thought that Stop meant the agent was done working. Not really.

In many situations where Claude needs to wait for some long-running task, it can start a background task or a subagent to do that. In these cases it does fire a Stop hook, but it says it is waiting for something to finish. When that happened, my script would "type" /exit and the agent would ask for confirmation before exiting, but there was nothing to confirm or deny, so the flow just broke.

So what I did instead of just exiting was to ask Claude. My Stop hook would type a question: "If there are no background jobs you're waiting for and you're done working reply with 'done' only. If you are waiting for background jobs reply with 'waiting' only."

The Stop hook input JSON includes a last_assistant_message field with the text of Claude's final reply for that turn. The hook reads it and routes on its content:

"done" → really done, send /exit to end the session.
"waiting" → tool or subagent still in flight; do nothing, the agent will trigger a new Stop when whatever it's running ends.
anything else → ask again.

The first time a session stops, last_assistant_message is whatever Claude was saying (usually a summary of work) so we nudge. Claude reads the nudge, classifies its own state, replies with a single word. That reply triggers another Stop. That second Stop's last_assistant_message is "done" or "waiting", and the hook acts on it.

StopFailure: retry with a counter

Just as I was testing the script, Claude started having API issues and returning a bunch of server errors. Kinda lucky in a weird way, as it exposed a potential issue with this approach.

StopFailure is fired when a turn ends because of an API error. We can't tell the difference between recoverable and non-recoverable failures from inside the hook, so we retry up to a limit and then give up.

The handler keeps a counter file at $TMPDIR/<session-id>. On each failure it increments. For the first five failures it types Up + Enter into the tmux pane after a ten-second pause. Up recalls the previous prompt in Claude's history and Enter re-submits it. On the sixth, it removes the counter and types /exit. Five retries with a 10s baseline have been enough to ride out every transient I've hit; if you have a permanently broken auth or billing setup, you'll burn through five retries and then exit, which is probably better than what claude -p would do in this situation.

claude-auto

Plugins are supposed to be installed in your agent's configuration, but Autonomy is different: it is only needed in targeted situations. claude-auto handles that, plus a few other useful things.

claude-auto does four things:

Generates a fresh UUID for --session-id, so the transcript can be retrieved later.
Loads the plugin via --plugin-url https://github.com/gpambrozio/Autonomy/archive/refs/heads/main.zip so there's no install step for the user. Claude Code fetches the zip on the fly.
Routes stdin/stdout/stderr so that the session renders on the terminal even when the caller piped us into tee.
Also, after the session ends it pipes the whole thing through claude-transcript so you have something to scroll back through (or, with --log <file>, written to a file).

claude-auto itself doesn't know about CLAUDE_AUTO_QUESTIONS_OK. It just doesn't strip the environment, so whatever you export reaches the hooks.

The typical invocation is:

claude-auto "do a thing"

You can also add any other flags you'd pass to claude:

claude-auto --dangerously-skip-permissions --effort max --model opus "/github-issue $1"

Getting Claude Code to render when stdout is piped

This was a bit tricky. In some of my scripts I was capturing the output of claude -p into a log file, so when I replaced it with claude-auto I did this:

claude-auto "..." | tee log.txt

Now Claude's stdout is the pipe to tee, not a TTY. When Claude detects that stdout isn't a TTY, it falls back to plain-text non-interactive output, which is the same as -p and would probably charge you accordingly.

Ironically, I used Claude to figure out how to get itself to still behave as if it were in a TTY even though I was piping stdout.

As with many shell tricks Claude knows, I don't fully understand how this works. Claude's explanation is this:

In the realistic call shapes, stdin is still a TTY even when stdout is piped. The shell only redirects what the pipe captures. If you run cmd | tee log, the pipe attaches to cmd's stdout; the parent shell's stdin (and cmd's stdin, by inheritance) is still your terminal. So I just dup the inherited stdin into stdout and stderr:

if [ -t 0 ] && [ -t 1 ] && [ -t 2 ]; then
    claude ... "$@"             # nothing to fix
elif [ -t 0 ]; then
    claude ... "$@" 1>&0 2>&0   # stdin is a TTY, dup it into the others
else
    claude ... "$@"             # no TTY anywhere, let claude decide
fi

1>&0 2>&0 makes fd 1 and fd 2 dups of fd 0. They share the same open file description as the inherited stdin, which is a normal pty fd opened O_RDWR by the shell. Bun is happy, the TUI renders on the actual terminal, the pipe still gets whatever claude-auto writes to stdout after Claude exits, which is the transcript dump.

claude-transcript

I wanted a way to get a transcript of the session afterwards, just in case something went wrong or to be able to see what it did.

There are many projects out there that do that, but I had Claude whip up a simple script.

claude-transcript is about 100 lines of Python that walks the JSONL file Claude saves for every session and prints a chronological list of just the parts I care about:

## [1] 2026-05-14 09:12:03 — USER
Implement the new caching layer described in issue #42.

## [2] 2026-05-14 09:12:18 — CLAUDE
I'll start by reading the existing cache implementation and the issue
description to understand the requirements.

## [3] 2026-05-14 09:15:47 — CLAUDE
Implementation done. Tests pass. PR opened at #167.

claude-auto calls it on every exit, so every session ends with a self-contained log on stdout (or in the file you passed to --log).

Limitations / caveats

tmux required. The whole mechanism is tmux send-keys.
StopFailure retries everything. It can't distinguish a 429 from a 401, so a session with broken auth will retry five times before exiting.
No questions by default. Unattended runs deny AskUserQuestion at the PreToolUse hook. If your automation depends on a human being there to answer, set CLAUDE_AUTO_QUESTIONS_OK=1 and attach to the tmux session.
It's a workaround. Anthropic could try to detect tricks like this and treat them as -p. My guess is that all these subscriptions will cease to exist or start to get severely limited anyway.

Try it

Plugin repo: github.com/gpambrozio/Autonomy
Drop bin/claude-auto and bin/claude-transcript on your $PATH, install tmux, start a tmux session, and run claude-auto "do a thing". The plugin is fetched from GitHub on every invocation; there's no install step beyond that.