How It Works

​

Overview

​

Key terms

• Run: a single, short‑lived execution created by an incoming event (e.g., PR opened, review requested).
• Devbox: an ephemeral VM Charlie starts for a run to check out code, install dependencies, run commands, and make changes.

​

What triggers Charlie

• GitHub (required)
  • Pull request opened or marked “Ready for review”
  • New commits pushed to an open pull request
  • Review requested for @CharlieHelps or a comment mentioning @CharlieHelps
  • PR review posted (human feedback on Charlie’s PR)
• Slack
  • Messages that mention @Charlie in a channel or thread where the app is installed
• Linear
  • Issues from teams linked to a repo

​

What happens during a run

1. Gather context
   • Reads only what is needed from the triggering platform(s): PR diffs, relevant files, comments, labels, assignees.
   • Loads the repository’s .charlie/config.yml and any project instructions that exist.
   • Pulls linked context from Slack/Linear/Sentry when relevant and connected.
2. Start an ephemeral compute environment
   • Spins up a fresh, temporary VM (“devbox”) with the repository checked out.
   • Installs dependencies as needed and can run your optional checkCommands (e.g., lint, tests, typecheck).
3. Think and act
   • Plans steps based on the event (review a PR, answer a question, make a change).
   • Executes changes inside the devbox when edits are needed.
   • Writes results back to the correct surface (GitHub, Slack, Linear).
4. Tear down
   • Shuts down the devbox. No internal state from the run is kept.

​

Visual overview

​

What Charlie can do

• Review pull requests (inline comments and summaries)
• Open pull requests and branches for fixes or refactors
• Push commits to existing PR branches (e.g., apply suggestions, fix build/lint)
• Comment and answer questions in GitHub, Slack, and Linear
• Create and update issues on GitHub or Linear

​

Important constraints

• No cancellation: once a run starts, it runs to completion.
• No hidden state: Charlie does not retain state between runs beyond what is posted to GitHub/Slack/Linear (and the commits/PRs Charlie creates).
• Principle of least access: Charlie only reads data needed to fulfill the current run and only in the tools that are connected.
• Ephemeral compute: every run uses a fresh devbox and is torn down afterward.

​

Usage tips

• Make events explicit
  • Mark PRs “Ready for review” when you want feedback.
  • Request a review from @CharlieHelps or mention @CharlieHelps in a PR comment to ask for help.
  • In Slack/Linear, mention Charlie directly and provide quick context (“check failing tests in module X”). If the thread is long, ask for a brief summary first and then state the task.
• Be explicit about the action
  • Say what you want: “open a PR”, “leave a comment diagnosing this”, “push a commit that…”.
• Include concrete context
  • Reference files, functions, packages, or lines when asking for a change.
• State constraints
  • Call out musts/must‑nots (e.g., “handle nulls; do not mutate global state”).
• Keep repo guidance close to code
  • Add .charlie/config.yml for optional checks and preferences.
  • Add project instructions under .charlie/instructions/ to steer responses.
• Let runs finish
  • Because runs can’t be canceled, start them when the PR or question is ready.

​

Build/test feedback

• GitHub Actions: Charlie can fetch logs via the GitHub CLI when asked to “fix the build.”
• Other CI (e.g., CircleCI): paste the failing job’s error snippet into the PR or Slack thread and ask Charlie to fix it; add any missing env vars in the dashboard so tests can run in the devbox.

​

Example PR review flow

​

Common prompts

• @CharlieHelps review this PR
• @CharlieHelps open a PR to add tests for edge cases in <path/to/file>
• @CharlieHelps leave a comment diagnosing this failure
• @CharlieHelps fix the failing tests in <package>
• @CharlieHelps create a PR from LINEAR-123
• @CharlieHelps check GitHub Actions logs for this run and suggest a fix