​
Overview

This page explains how Charlie reacts to events, what happens during a run, what Charlie can do, and the key constraints.

​
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

Charlie listens for events from the tools you connect:
  • 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
If Slack or Linear aren’t connected, those triggers simply don’t fire—GitHub alone is enough to get value.

​
What happens during a run

Each event creates an isolated “run.” A run is single‑purpose and short‑lived. It cannot be paused or canceled once it starts.
  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
Everything Charlie does is visible where it happens: in the PR, the issue, or the Slack/Linear thread.

​
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
Open‑source repositories are supported. See Open Source for the exact invocation rules.