woods

Claude Code plugin architecture

This document is the mental model behind how a Claude plugin gets installed. Normal plugin instructions tell you what to do; this document tells you why it works, what each piece actually is, and how the parts fit together. Reading it should take maybe ten minutes and save you hours of confusion later when something doesn't behave the way you'd expect from reading a plugin's surface docs alone.

The three-layer model

woods

Cowork vs. Code: which surface to use, and why

Anthropic's desktop app exposes two assistant surfaces — Cowork and Code — that look similar at the chat layer but are quite different underneath. The surface-level guidance ("use Code for developer work, Cowork for documents") is correct but doesn't explain why, which makes it hard to predict how each will behave in unfamiliar situations. This document is the mental model.

There are two axes that distinguish the two surfaces: trust model

woods

# Allow access to the vault service from the public and private subnets
# Note that this doesn't allow access from the internet; it just allows
# traffic over the private network from hosts that reside in either of our
# two subnets.
resource "aws_security_group_rule" "vault" {
  security_group_id = "${aws_security_group.security_group.id}"
  type = "ingress"
  from_port = 8200
  to_port   = 8200
  protocol  = "tcp"

woods

# Get all patch versions of all kernels on the system
all_kernel_patch_versions=$( dpkg -l | egrep 'linux-headers-3.13.0-[0-9]+-generic' | awk -F '-' '{print $4}' | sort -n )

# Exclude any kernels that are in use (hard coded; you must CUSTOMIZE THIS PER MACHINE)
unused_kernel_patch_versions=$( echo "$all_kernel_patch_versions" | egrep -v '1[67]' )  

for n in $unused_kernel_patch_versions ; do 
  echo
  echo "========== $n ========="
  echo

woods

        <tr>
          <td colspan="4" class="align_right"><strong>{{ 'customer.order.total' | t }}</strong></td>
          <td class="text-right"><strong>{{ order.total_price | money }} {{ order.currency }}</strong></td>
        </tr>

woods

for n in 57 61 68 77 79 83 85 86 87 88 91 92 93 95 96 98 100 101 103 105 106 107 108 109 110 111 112 113 115 116
do 
  apt-get purge -y \
    linux-headers-3.13.0-$n \
    linux-headers-3.13.0-${n}-generic \
    linux-image-3.13.0-${n}-generic \
    linux-image-extra-3.13.0-${n}-generic
done

woods

Over time, West Arete has developed a convention for how we organize our spec directories. This arrangement has been very successful for us over many years and many projects. We'd love to extract it into some kind of framework/gem, but have never managed/invested to do so. So at the very least we can share this writeup of what we've found to be useful, in the hope that it's useful to others.

The top level of our spec directory looks like this:

spec/
  spec_helper.rb

woods

curl -s https://ip-ranges.amazonaws.com/ip-ranges.json \
  | jq '.prefixes | map(select(.service=="ROUTE53_HEALTHCHECKS")) | map(.ip_prefix)'

woods

### Keybase proof

I hereby claim:

  * I am woods on github.
  * I am woods (https://keybase.io/woods) on keybase.
  * I have a public key ASBRwmuep3o_XIJa0bbb-0xxkdgyxWqCt-SEvK1MHlkjoQo

To claim this, I am signing this object:

woods

Friendly URLs

By default, Rails applications build URLs based on the primary key -- the id column from the database. Imagine we have a Person model and associated controller. We have a person record for Bob Martin that has id number 6. The URL for his show page would be:

/people/6

But, for aesthetic or SEO purposes, we want Bob's name in the URL. The last segment, the 6 here, is called the "slug". Let's look at a few ways to implement better slugs.