charmfile docs
Home
0.2.0-rc.3 macOS · Codex

The friendly field guide

Set it up once.
Keep moving.

Charmfile gives Codex a dependable setup, useful workflows, and a durable place to remember what matters. These docs take you from a safe install to a clean project restart—without turning your setup into a platform.

Start with four steps See the whole system

Local-first · open source · no account required · cloud optional

YOUR CHARMFILE ONE PRIMARY AGENT
  1. 01
    CoreA portable Codex profile and safe operating rules.
    always
  2. 02
    SkillsFocused workflows that load when the work needs them.
    on demand
  3. 03
    MemorySanitized outcomes and next steps in normal Markdown.
    optional
  4. 04
    ResumeGit state and project context in one read-only summary.
    any time

Your repository stays authoritative. You stay in charge.

01 / START HERE

From zero to healthy in four steps.

about 5 minutes

The standard setup installs Charmfile Core and makes the Memory workflow available. It does not choose a vault, enable cloud sync, or change your normal codex command.

  1. 01
    Clone

    Get the reviewed release from Charmfile’s canonical repository.

  2. 02
    Plan

    See every proposed change before anything is written.

  3. 03
    Approve

    Install only after the plan looks right to you.

  4. 04
    Check

    Run the doctor and start fresh with clear health evidence.

standard setup 
# Get Charmfile
git clone https://charmfile.com/git/charmfile.git
cd charmfile

# Review first, then approve
./scripts/install-charmfile plan
./scripts/install-charmfile install --yes

# Finish with evidence
./scripts/install-charmfile doctor
Open a new terminal and start a fresh Codex session after installation.
Prefer to let Codex guide the setup? Give the reviewed folder to Codex and paste this.
Use $install-charmfile to inspect this Mac and install the standard Charmfile Core + Memory configuration. Show me the exact plan and wait for approval. Preserve my existing setup, projects, secrets, and browser profile. Do not activate a vault or cloud mode. After installation, run the Charmfile doctor.

02 / CHARMFILE CORE

A dependable baseline, not another agent.

Codex remains the operator. Charmfile supplies a portable profile, clear working rules, a lifecycle command, and focused health checks. It keeps the useful defaults together without owning your machine or your projects.

SETUP

Clear defaults

Practical guidance for communication, safety, verification, and everyday work.

WORKFLOW

Skills when needed

Research, browser, frontend, server, and other methods load only for relevant tasks.

HEALTH

Visible checks

charmfile doctor makes the setup’s health legible instead of asking you to trust it.

one taskPrompt
durable rulesGuidance
repeatable methodSkill
exact actionTool
continuityMemory

03 / PORTABLE PROFILE

Your normal Codex stays normal.

Charmfile installs a separate profile and launcher. It carries safe, portable defaults while leaving your base configuration untouched.

  • Separate charmfile-codex launcher
  • Existing projects and plugin state preserved
  • No fixed model or personal machine paths
  • No private tools or credentials copied
YOUR EXISTING SETUPcodexunchanged
CHARMFILE PROFILEcharmfile-codexopt in when you want it

04 / MEMORY

Keep the outcome. Leave the transcript behind.

Charmfile Memory uses the separately versioned Codex Obsidian Sidecar to curate useful project continuity into normal Markdown. Activation is a second, reviewed step because it selects a private vault and installs a local service.

Memory keeps

  • Verified outcomes
  • Project phase and resume point
  • Important decisions
  • Ranked open work
  • Freshness and provenance

Memory excludes

  • Raw transcripts
  • Internal reasoning
  • Complete tool output
  • Credentials and customer data
  • Temporary metrics
1Install CharmfileCore + Memory workflow
2Activate local Memoryvault + Sidecar, separately approved
3Add cloud if wantedserver plan, separately approved

05 / PROJECT RESUME

Return to a project without starting over.

A tiny .charmfile/project.toml file gives the repository a portable identity. It points to the right project note without storing your private vault path or the memory itself.

01charmfile init

Preview the project identity. Add --yes only after reviewing it.

02charmfile resume

Read Git state, the latest outcome, open work, and the best restart point.

03charmfile status

Read installed layers, cached Memory health, and continuity freshness.

READ-ONLY OUTPUTNothing changed.
Project:       example-app
Current phase: Build
Last outcome: Checkout flow verified
Resume here:  Add the mobile error state
Memory:       fresh
Git:          clean

Important: resume and status never repair, sync, index, contact a cloud host, or change configuration. If Memory is unavailable, they say so plainly.

06 / CAPABILITY PACKS

Keep the core small. Add depth on purpose.

Core and Memory form the standard setup. Specialist packs add focused guidance without turning every session into a giant toolbox.

PackWhat it helps withInstall
BrowseroptionalLocal/public Playwright and explicit signed-in Chrome work--with-browser
FrontendoptionalResponsive, accessible UI implementation and QA--with frontend
ResearchoptionalSource-backed technical and product research--with research
MarketingoptionalAds, analytics, market evidence, and launch review--with marketing
InfrastructureoptionalVPS health, capacity, backups, and operations review--with infrastructure
Three.jsoptionalFocused 3D workflows loaded by topic--with threejs

Use --preset full for the complete pack set. Updates preserve the packs you selected; they do not silently add more.

07 / OPTIONAL CLOUD

Local by default. Server-compatible by choice.

You do not need a VPS. Cloud compatibility exists for people who want their Markdown vault replicated or maintained on infrastructure they own.

DEFAULT

Local Memory

Everything runs on your Mac. No server and no model API are required.

Best place to start
OPTIONAL

Vault sync

Use a sync system you choose to make the Markdown vault available elsewhere.

No maintenance worker
ADVANCED

Maintenance worker

A reviewed Linux host can run fenced, bounded maintenance with independent backups and health gates.

Separate plan required

08 / SAFETY

You can see the boundary.

Charmfile is intentionally conservative around the parts of your system that matter most.

  • PLAN FIRST

    Install and update show their work before approval.

  • BASE CONFIG

    Your normal Codex configuration is not edited.

  • MANAGED FILES

    Unmanaged targets are preserved or block installation instead of being overwritten.

  • SECRETS

    Reusable values stay in macOS Keychain, never in the package or memory vault.

  • BROWSER

    Signed-in Chrome attachment remains an explicit user-approved action.

  • AUTHORITY

    Charmfile cannot make unrestricted permissions safe; you still choose what the agent may do.

09 / TROUBLESHOOTING

A few useful answers.

Does Charmfile replace Codex?

No. Codex remains the primary agent and operator. Charmfile supplies portable configuration, reusable workflows, health checks, and optional project continuity.

Do I need Obsidian or a server?

No server is required. Core works without Memory. The default setup makes the local Memory workflow available, but you choose and approve a vault separately. Cloud is a third, optional phase.

Why did the installer stop at an existing file?

That is a safety feature. Charmfile does not replace an unmanaged file at a path it owns. Review the reported target and decide explicitly whether to move, merge, or preserve it.

Why does resume say Memory is unavailable?

The project identity can exist before local Memory is activated. Resume reports the expected memory reference and stops there; it does not install or repair anything behind your back.

What platforms are supported?

The current release candidate supports macOS and Codex. Linux is used only for the optional reviewed cloud-worker topology.

Is Charmfile an OpenAI product?

No. Charmfile is an independent open-source community project and is not affiliated with or endorsed by OpenAI.

10 / REFERENCE

Go deeper when you need to.

The friendly guide covers the normal path. These plain-text contracts are the detailed source for operators, reviewers, and contributors.

01InstallationPresets, updates, and Memory activation 02Project resumeManifest and read-only command contract 03MemoryWhat continuity keeps and excludes 04CloudLocal, sync, and worker modes 05Capability packsDefault and optional workflows 06ArchitectureAuthority, layers, and boundaries 07SecuritySupported version and safety model 08Product contractNormative product and release scope
READY?

Start small. Add continuity when it earns its place.

Back to setup