​
Overview

This page describes repository‑level configuration, instruction files that Charlie reads, and environment variables used during runs. This guide covers three knobs you control per repository:
  • .charlie/config.yml – feature flags and run/verify commands
  • Project “rules” and instructions – Markdown files Charlie reads for context
  • Per‑repo environment variables – injected into Charlie’s ephemeral VM (Devbox)

​
1) Repository config: .charlie/config.yml

Location: .charlie/config.yml on the default branch. Changes take effect after merging to the default branch. If the file is missing or invalid, safe defaults are used. Schema and behavior:
  • ignorePatterns: string[] – Glob patterns to exclude from extended diffs and context gathering. Useful for generated code, vendored assets, or giant lockfiles.
  • checkCommands: { fix?, lint?, types?, test? } – Shell commands Charlie can run inside the Devbox.
  • checkCommands: { fix?, lint?, types?, test? } – Shell commands Charlie can run inside the Devbox.
    • All commands run from the repository root inside the Devbox.
    • fix is run after Charlie edits code (format/lint autofix, codegen, etc.).
    • types enables a TypeScript verification step when provided.
    • lint runs your linters (for example, ESLint).
    • test runs your unit tests (not E2E or integration tests).
    • lint and test are only enforced when beta.forceAllCheckCommands is true.
  • beta – Experimental feature toggles:
    • automaticallyReviewPullRequests (default: true) – Auto‑request a review from Charlie when a PR is opened or marked ready for review.
    • skipEmptyReviews (default: false) – If the generated review has no significant findings, skip posting entirely.
    • filterReviewComments (default: false) – Classify and post only helpful/actionable comments.
    • canApprovePullRequests (default: false) – Allow Charlie to post an “Approve” review when appropriate (never for Charlie-authored PRs).
    • forceAllCheckCommands (default: false) – When true, treat lint and test in checkCommands as required verifiers.
Example: 
ignorePatterns:
  - '**/*.lock'
  - '**/dist/**'
  - '**/generated/**'
checkCommands:
  fix: bun run fix
  lint: bun run lint
  types: bun run typecheck
  test: bun run test
beta:
  automaticallyReviewPullRequests: true
  skipEmptyReviews: true
  filterReviewComments: true
  canApprovePullRequests: false
  forceAllCheckCommands: false
Notes:
  • Invalid or misshaped values are ignored per‑field and replaced with defaults (other valid keys are preserved).
  • ignorePatterns affect Charlie’s extended diff during reviews; large or noisy files listed there won’t drive comments.

​
2) Project instructions (“rules” files Charlie reads)

Charlie scans a small, well‑known set of instruction files from your repo and includes them in its working context. Use these files to teach Charlie repo‑specific conventions, pitfalls, naming, architecture guidelines, and common mistakes to avoid. Keep them short, concrete, and evolving. Recognized files and scope:
  • .charlie/instructions/*.md – Global to the entire repo.
  • CLAUDE.md – Scoped to its directory and all descendants.
    • Example: services/db/CLAUDE.md applies to services/db/**.
  • AGENTS.md – Scoped to its directory and all descendants.
    • Example: apps/api/AGENTS.md applies to apps/api/**.
  • .cursor/rules/*.mdc – Modern Cursor rules; scope is the directory that contains the .cursor/rules folder.
    • Example: apps/web/.cursor/rules/auth.mdc applies to apps/web/**.
  • .cursorrules (repo root legacy) – Global to the entire repo.
Writing effective rules:
  • Prefer imperative, testable directives over philosophy. Show tiny code snippets when helpful.
  • Capture recurring review feedback, gotchas, naming/typing rules, file layout, and internal API contracts.
  • Update continuously as patterns solidify; the goal is to prevent repeat mistakes.

​
Scoping instructions by package or part of the tree (monorepos)

You can keep high‑level guidance global and add tighter rules for specific packages, apps, or subfolders. Charlie automatically includes the rules that match the files it’s working on. This per‑package or per‑directory scoping is especially useful when team ownership maps to the repo’s folder tree, because each team can keep its guidance next to the package or subfolder it owns.
  • Global (applies everywhere): put Markdown files under .charlie/instructions/ or use a repo‑root .cursorrules.
  • Directory/package‑scoped (applies to that folder and all descendants): add a CLAUDE.md or AGENTS.md inside the folder, or place Cursor rules under a .cursor/rules/ folder inside that area.
Example layout in a monorepo: 
.
├── .charlie/
│   └── instructions/
│       ├── conventions.md       # global
│       └── reviewer-notes.md    # global
├── packages/
│   ├── payments/
│   │   └── CLAUDE.md            # applies to packages/payments/**
│   └── web/
│       └── AGENTS.md            # applies to packages/web/**
└── apps/
    └── api/
        └── .cursor/
            └── rules/
                └── auth.mdc     # applies to apps/api/**
Behavior and tips:
  • Rules are additive: global rules always apply; folder‑scoped files are added when Charlie works inside that subtree.
  • Prefer placing more specific or exception guidance in the narrowest applicable folder. Keep global rules short and broadly true.
  • Use focused files per topic (e.g., errors.md, logging.md) to control token budget and keep guidance scannable.
  • Filenames are case‑sensitive and must be exactly CLAUDE.md or AGENTS.md when using those patterns.
How to verify it’s working:
  • In a PR or Slack thread, ask Charlie to cite which rule files it used (e.g., “cite the instruction files you relied on”). Charlie will reference paths like .charlie/instructions/conventions.md and packages/payments/CLAUDE.md when they are in scope.

​
3) Environment variables (Dashboard → Manage → Repository)

Add per‑repository environment variables in the dashboard. Charlie injects these into each ephemeral Devbox so Charlie can build, run tests, and start dev tools like a teammate on your machine. What’s already provided when integrations are connected:
  • GH_TOKEN – Installation access token for the repo (always set by Charlie).
  • LINEAR_API_KEY – When Linear is connected.
  • SENTRY_AUTH_TOKEN and SENTRY_ORG – When Sentry is connected.
Common variables you might add:
  • NPM_TOKEN (or NPM_AUTH_TOKEN) – Private registry access; also enables installing internal CLIs in the Devbox.
  • Remote cache or CI tokens used by your build (e.g., TURBO_TOKEN/TURBO_TEAM if you use Turborepo remote caching).
  • E2E/dev server knobs (e.g., PLAYWRIGHT_*, CYPRESS_*, framework‑specific NEXT_PUBLIC_*, VITE_*).
  • Service creds needed for non‑production runs (SDK read‑only keys, mock service URLs, etc.).
Guidance:
  • Prefer non‑production, least‑privilege tokens. The Devbox is ephemeral and torn down after the run.
  • If your repo uses Git submodules or private secondary registries, include any extra tokens those tools require.
CI tips:
  • GitHub Actions: asking Charlie to “fix the build” lets Charlie fetch logs automatically with the GitHub CLI.
  • Other CI (e.g., CircleCI): paste the failure snippet into the PR/Slack thread and ask Charlie to fix it; ensure any CI‑only env vars are added in the dashboard so tests can run in the Devbox.
Values are encrypted at rest and hidden in the dashboard after you save them.

​
Quick FAQs

​
“We merged config changes but nothing changed.”

Config is read from the default branch; ensure the file lives at .charlie/config.yml and changes are merged to default.

​
“Charlie approved a PR.”

That only happens if beta.canApprovePullRequests is true, the review found no significant issues, and the PR isn’t authored by Charlie.

​
“Lint/tests weren’t enforced.”

Provide the commands in checkCommands and set beta.forceAllCheckCommands: true to require lint and test.
For minimum setup steps, see the Setup guide.