​
Overview and usage

This page provides a compact, LLM‑friendly reference for common questions and practical guidance. Entries are concise, uniquely titled, and self‑contained. For setup and core behavior, see:

​
FAQ

​
Does Charlie persist state between messages or threads?

  • No persistent VM across events: each message or event starts a fresh, ephemeral environment (a new “run”).
  • Continuity is achieved by using deterministic branch names and by re‑reading the prior thread: on a new message, Charlie clones the repo, checks out the deterministic branch, pulls from remote, and reads the Slack thread context to infer prior decisions. This can make it feel like the VM persisted even though it did not.
  • Tip: explicitly name or pin the branch you want and keep using the same thread to reduce branch drift. See Tips & Tricks → Branch control.

​
Can Charlie process images or screenshots in Slack or PRs?

  • Yes. Charlie parses screenshots/images in GitHub PR/issue comments and in connected Slack/Linear threads. Add a short caption or highlight the relevant area for best results.

​
How does Charlie decide what to review or comment on in PRs?

  • Reviews are intentionally non‑agentic: Charlie gathers a bounded, deterministic context (diff, nearby files, comments, your rules) and reviews that. Charlie does not deep‑crawl the whole repo during the review itself. When information is missing, Charlie may use “if X isn’t handled elsewhere…” style caveats.
  • To make reviews crisper, provide intent in the PR description and link to related files/decisions. See Tips & Tricks → Writing PRs Charlie reviews well.

​
Will Charlie automatically run tests, lint, and formatting before committing?

  • Tests/lint: Charlie typically runs tests and lint locally during a run when asked.
  • Formatting: “Format before commit” helps avoid CI failures from minor nits (e.g., newline/end‑of‑file). Treat this as a requested improvement, not guaranteed behavior. Workarounds are listed under Tips & Tricks → Pre‑commit hygiene.

​
How can Charlie help with CI failures and test logs?

  • GitHub Actions: Ask Charlie to “fix the build”; Charlie can use the GitHub CLI to pull logs and iterate.
  • Other CI (e.g., CircleCI): Provide the failing job’s error text or a machine‑readable results file in the PR/Slack thread and ask Charlie to fix it.
  • Noise control: If auto‑reacting to webhooks feels noisy, keep the loop manual (ask Charlie to check CI on request) or add simple backoff rules.

​
Can Charlie access Sentry or other observability tools?

  • Sentry: Yes—connect Sentry via a token and then ask Charlie to query incidents and propose fixes. Use the dashboard to provide auth; then ask in Slack/PRs to “check Sentry for this error.”
  • Other providers: Paste relevant logs or expose machine‑readable outputs Charlie can ingest.

​
Where should we put rules/instructions so Charlie follows org‑specific conventions?

  • Charlie reads common agent instruction files (e.g., rules used by Cursor/Claude/OpenAI) and project docs kept alongside code. You can place rules in the repo root and in specific subdirectories; Charlie will find and use them.
  • Good patterns: directory‑scoped rules for tricky systems (e.g., Hasura triggers), and a simple glossary for team‑specific terms that lives in your Charlie instructions (for example, under .charlie/instructions/).
  • See Configuration & advanced setup for how repository‑local instructions interact with .charlie/config.yml.

​
Does Charlie remember long Slack threads well?

  • Long threads can degrade performance. Effective workaround today: ask Charlie to summarize the important parts, start a fresh thread with that summary, and continue there.
  • Improvements to context handling are being explored; rely on How it works for current limits.

​
How should we provide environment variables or special setup so tests run for Charlie?

  • Use the dashboard to add repository environment variables that Charlie can read during runs. Only add non‑sensitive values appropriate for CI‑like use.
  • If your repo needs conditional steps when Charlie is running, use a custom variable (for example, CHARLIE=1) in your scripts. See Configuration & advanced setup.

​
Can we combine or migrate context between two separate Charlie threads?

  • For complex workstreams, a practical approach is to ask Charlie to summarize each thread and then start a new thread with those summaries included.

​
Tips & Tricks

​
Repository hygiene

  • Run Knip regularly to prune unused files, exports, and dependencies. Add a script (for example, knip) and treat warnings as actionable; keeping references clean improves navigation and reduces false positives in reviews.
  • Configure GitHub Autolinks in Repository settings → Autolink references so issue keys like TEAM-123 and ticket IDs in commit messages/PRs become clickable. This keeps discussion and history connected across tools.

​
Writing PRs Charlie reviews well

  • State intent upfront in the PR description (especially for pure refactors, framework upgrades, or JS→TS conversions) so comments stay concrete.
  • Link relevant files/decisions. If code depends on config/metadata (e.g., Hasura), point Charlie to where that lives in the repo.
  • Screenshots/images are supported. Include a brief caption and, when relevant, link to code paths so suggestions stay concrete.

​
Rules and glossary placement that actually help

  • Put instruction files close to the code they guide. Directory‑scoped rules help teach Charlie about event pipelines and trigger wiring.
  • Maintain a lightweight glossary (“this term means X in your codebase”) to reduce repeated explanations.
  • Cross‑check with Configuration & advanced setup to understand how local instructions complement .charlie/config.yml.

​
Branch control in Slack‑driven work

  • Be explicit about the branch: “Use branch X for this thread.” Because each message starts fresh, clarity reduces accidental new branches.
  • If Charlie commits to the wrong branch, say so directly and restate the target branch; Charlie re‑reads the thread and will correct course.

​
Task batching to reduce CI churn

  • When acknowledging multiple inline review comments (e.g., “yes” to three suggestions), ask Charlie to collect them and push a single commit to avoid multiple CI runs. Today this is best‑effort if you ask explicitly.

​
Pre‑commit hygiene while formatting isn’t automatic

  • Ask Charlie to run your repo’s formatter/linter before pushing: e.g., “run lint and format, then commit.” This avoids CI failures from trivial nits.
  • If CI uses non‑default formatters (e.g., Biome), mention them by name in your instruction so Charlie invokes the right script.

​
Working with CI beyond GitHub Actions

  • CircleCI and others: paste failing error output (or attach machine‑readable test reports) and ask Charlie to fix tests. Providing artifacts helps.
  • Rate/loop control: If you invite Charlie to auto‑respond to CI webhooks, consider a simple backoff (e.g., “stop after 4 failed tries and wait for a human”). Treat this as a preference pattern, not a built‑in limit.

​
Managing long conversations

  • When a Slack thread grows long (hundreds of messages), ask Charlie to summarize decisions, open a new thread with that summary, and continue from there. This keeps context sharp.

​
Surfacing logs and observability

  • Sentry: after connecting with a token via the dashboard, ask “Check Sentry for this error and propose a fix” to have Charlie cross‑reference source and open a PR.
  • Other providers (Better Stack, CloudWatch): until native integrations exist, paste relevant log excerpts or link artifacts; Charlie can reason over the content.

​
Handling complex event wiring (Hasura, webhooks, etc.)

  • If behavior depends on metadata/config files (e.g., Hasura YAML), point Charlie at the exact paths and add directory‑local rules that explain the trigger flow. This dramatically improves search/navigation inside the repo.

​
Asking for tests and local validation

  • Ask Charlie to generate or update tests and to include local run output in replies. If a PR lacks tests, ask for them explicitly and request the local test output snippet.

​
When two threads converge

  • If work diverged across two Slack threads, ask Charlie to summarize each thread, then start a clean thread with both summaries and an explicit goal. This is the most reliable way to “merge contexts” today.

​
Troubleshooting patterns

​
“It says ‘build passed locally’ but my build fails”

  • Environments may differ (missing env vars, browser dependencies, DB). Provide required env vars via the dashboard and mention any special setup. Ask Charlie to re‑run tests after injecting env.

​
“Charlie fixed some Dependabot alerts but not all”

  • Tell Charlie explicitly how many remain or list them; if needed, iterate with “keep going until all N are fixed.”

​
“Too many branches were created”

  • Restate the single authoritative branch for the thread and ask Charlie to consolidate changes there. If a “PR for class of errors” is desired, say so (e.g., “open a separate PR to fix the stacked errors”).

​
“CircleCI logs are painful to copy over”

  • Instead of copying UI text, attach the job’s machine‑readable results (e.g., Playwright JSON) to the PR or paste the raw failure block; then ask Charlie to fix the failing cases.
For current product behavior and configuration details, see Initial setup & installation, How Charlie works, and Configuration & advanced setup.

​
Scenario tips

​
Code Reviews

  • Mark PRs “Ready for review” or request a review from @CharlieHelps to trigger a review.
  • State intent in the PR description (e.g., “pure refactor,” “framework upgrade”) and link any related files or prior decisions.
  • Ask for focus (“limit feedback to correctness and TypeScript types”) or for a targeted pass (“only flag potential regressions in auth”).

​
Technical Discussions

  • Ask Charlie to explain modules or flows and to cite files/lines in the answer.
  • Use “summarize this thread, then propose options with trade‑offs” to reach decisions faster.
  • When searching for docs or patterns, name the feature and preferred locations (“look for rate‑limit docs in docs/ and src/middleware/”).

​
Code Contributions

  • Be explicit about scope, branch, and acceptance criteria (“open a PR on feat/payments-v2 that adds tests for X; all tests must pass”).
  • Ask Charlie to run formatter/linter/tests before pushing and to include the local output in the reply.
  • If changes span packages, request a single commit or a single PR unless you ask for a split.

​
Linear Integration

  • Link the GitHub repository to the correct Linear team first; then ask “create a PR from TEAM-123.”
  • Specify branch naming and PR title conventions if you have them; Charlie will follow your guidance.
  • Ask for bi‑directional context (“include key details from this Linear issue in the PR description”).

​
Slack Integration

  • Pin the working branch at the start of a thread and keep all follow‑ups in that thread.
  • Use Slack for quick iterations; when the change is ready for full review, request a GitHub review from @CharlieHelps on the PR.
  • For long threads, ask for a summary and continue in a new thread with that summary to keep context sharp.
  • Ask @Charlie to create a well‑written Linear or GitHub issue from the Slack thread; Charlie will pull relevant context and draft it for you.

​
If you’re not sure @Charlie understands or is correct

Ask @Charlie probing questions that require evidence and verification. Ask @Charlie to explain reasoning back before acting. This turns a guess into a check.
  • Ask @Charlie to restate your request and the expected outcome in their own words (confirmation of understanding)
  • Ask for concrete evidence: cite specific files, line ranges, commits, or config/instruction files relied upon (for example, .charlie/config.yml, rules under .charlie/instructions/)
  • Ask to list assumptions, unknowns, and what additional info would change the answer
  • Ask for a step‑by‑step reasoning outline or plan, and what alternatives were considered and rejected
  • Ask for a minimal test, reproduction, or quick validation step, with expected vs. actual results
  • Ask to surface relevant command output or logs (when applicable) from the run/devbox, or to point to existing CI logs referenced
  • Ask to annotate where a suggested change applies in the diff (file + line) and why
  • Ask for a brief comparison of two options with tradeoffs and a recommendation
  • Ask for a confidence level and what would increase it