← Dev log　|　日本語版

Where I got stuck connecting GitHub

Article one. Last time I wrote "start with GitHub, whatever else you do" — but actually connecting it turned out to be where I got properly stuck. Here's how the connection works, what tripped me up, and how I ended up moving to Composio.

At first, everything happened inside the chat

When the HTML behind this scene passed 1 MB, the chat workflow broke down

Early on, the whole game lived in a single HTML file that I pasted back and forth in conversation with the AI. Paste the file, get the fixed version back, paste it again. Once the file passed a few hundred kilobytes, this fell apart.

Every round trip, the AI would subtly change something else. Things broke without me noticing
"Where we left off" didn't exist for the AI. I explained everything again each time
Eventually even I couldn't tell which version was current

Going through GitHub solves all three. The latest is on main. The differences are visible in the PR. The reasoning survives in the Issue. Obvious, really — but if you start out treating it as "a conversation with an AI", it's easy to put off.

How the connection works now

Three paths, used together.

1. Issues as the starting point for implementation

The flow goes like this. First I tell the AI in chat what I want. The AI organises that into a goal, a list of changes and a definition of done, and files it as a GitHub Issue. If that Issue mentions the AI, a second AI branches off, edits the code and opens a PR. I look at the diff and the preview, and if it's fine I say "merge it" — the AI performs the merge itself.

So what I write is the chat instruction, not the Issue. The AI writes the Issue. Turning a vague request into something implementable is the AI's job; my job is checking that the translation is right.

The real benefit is that large files never touch the chat. The AI works inside the repository.

2. Calling the GitHub API from the chat side

Filing Issues, checking PR status, reading and writing small files, re-running workflows — the lightweight operations happen straight from the chat. This is where most of the pain was, as you'll see below.

3. The decision to merge is mine; the operation is the AI's

Nothing reaches production until I say "merge it". The judgement is mine, the merge and deploy are performed by the AI. That the AI never merges unprompted is written into the rules document.

Things to watch out for

Large files can't be read the normal way. In my setup, fetching the game file (about 1 MB) through the chat-side connection times out. Anything over 500 KB goes through an Issue so the AI can touch it directly
The API silently truncates. GitHub's file-contents API omits the body when a file is large. You have to list the directory, take the SHA, and fetch through the blob API instead
Workflow files are a special case. There was a period when the AI couldn't write to .github/workflows/ because of permissions. It can now, but since it's the backbone of CI/CD I treat it more carefully than other files. The flow is the same though: I give the instruction in chat, the AI writes the change
Bot-authored PRs need approval before Actions run. More than once I thought the preview deploy was broken when it was simply waiting for approval
Don't stuff one Issue full. Too many changes and the AI stops partway. Three changes per Issue is my limit
Keep the project's current state fully visible in GitHub. The latest code, the open Issues and PRs, the rules. All of it should be readable from GitHub alone. Don't rely on chat history or AI memory — more on that in the next article

Getting to Composio

I rebuilt the path between the chat and GitHub several times.

First: a Docker-based connection

I started by connecting Claude's desktop app to GitHub via MCP. That connection runs on top of Docker, which means Docker Desktop has to be running first.

That turned out to be quietly exhausting.

Forget to start Docker and everything halts with "Docker not found". The AI won't tell you why, so you sit there puzzled
Even when it works, fetching the large game file times out
Let the connection go stale and it stops responding. Fixing it means fully quitting and restarting the app
If the connection dies mid-conversation, that conversation never recovers. You have to open a new one

My troubleshooting notes from that period still exist: "Docker not found → check Docker Desktop is running", "MCP connection error → full quit and restart", "no MCP response in an existing chat → continue in a new chat". Time meant for development was going into keeping the connection alive.

Then: switching to Composio

A few months later, Claude became able to use Composio, a general-purpose tool-integration service.

The trigger was simple. The Docker connection kept failing, and a Docker-based connection only works on the machine that's running it — nothing could be done from a phone while out. So I asked Claude, "isn't there something better?", and it suggested going through Composio to hit the GitHub API directly.

After switching: no Docker. I can work from a phone without turning on the computer. The AI can check whether the connection is alive. Fine-grained operations like fetching a file's SHA or re-running a workflow all became possible.

The trade-off is that there's more to remember — how to call the API, the shape of the response, how to retry on failure. Having the AI rediscover all that every time is wasteful, so I keep a document in the repository saying "for this operation, call this API like so", and have the AI read it.

The criterion I used

Simple: can I work out what's wrong when it breaks? The Docker connection was comfortable while it worked, but when it stopped neither the AI nor I could tell what was happening — and it only worked while sitting at the computer. A slightly more manual path whose insides are visible lasts longer.

What I wish I'd known

Create the repo on day one and route all AI work through it
Assume large files can't be read directly; give the AI a way to work inside the repo
Keep the project's current state entirely in GitHub. Never rely on chat or memory
Make "I check and instruct, the AI operates" a rule from the start
Pick a connection whose health you can verify yourself (the Docker route was opaque)

Series: "I wish I'd known this from the start"

← Back to the dev log