Profile Management

MoAI-ADK’s profile system lets you manage multiple Claude Code configurations in isolation. Separate work vs. personal setups, or high-quality vs. cost-saving sessions, into one profile each, and you no longer need to change model, language, and display settings every time.

Since one profile is one CLAUDE_CONFIG_DIR, a profile becomes a conflict-free isolation unit in harness scenarios where multiple agents need different models, effort levels, and output styles. So for a manager agent that switches between work and experimental setups on the same machine, a profile is effectively an independent working environment.

A profile is an isolated Claude Code configuration directory (CLAUDE_CONFIG_DIR). Each profile maintains independent settings, model selection, and language environment.

~/.moai/claude-profiles/
├── default/           # Default profile
│   ├── settings.json
│   └── settings.local.json
├── work/              # Work profile
│   ├── settings.json
│   └── settings.local.json
└── personal/          # Personal profile
    └── ...

Displays all available profiles.

moai profile list

Runs the interactive setup wizard.

moai profile setup          # Set up the default profile
moai profile setup work     # Set up the "work" profile

Wizard configuration items:

• Identity: user name, role
• Languages: conversation language, code comment language
• Model Settings: default model, 1M context model selection
• Display: output style, status line settings

Displays the name of the currently active profile.

moai profile current

This value reflects the global record, so when different projects remember different profiles, read it together with the limitations in Automatic Profile Selection.

Deletes a profile.

moai profile delete old-profile

Specify a profile with the -p (or --profile) flag.

moai cc -p work          # Run Claude with the work profile
moai glm -p cost-save    # Run GLM with the cost-save profile
moai cg -p team          # Run CG mode with the team profile

Info

A profile given with -p always takes precedence. To see which profile is used when you do not specify one, read Automatic Profile Selection below. The first time a profile is used, the setup wizard starts automatically.

Running moai cc without -p picks a profile by consulting the record in ~/.moai/claude-profiles/launch.yaml. That record is updated every time you launch a named profile with -p.

Note

The per-project memory described below ships in the next release. The current release (v3.0.1) keeps only a single global record (last_profile), so specifying a profile with -p in project B overwrites the value project A had remembered.

Alongside the global record, launch.yaml maintains a projects: map keyed by the project’s absolute path. A launch without -p resolves the profile in this order:

1. The profile the current project remembers (a projects: entry)
2. The global record (last_profile)
3. The default profile

If a recorded profile’s directory has already been deleted, it is skipped and resolution moves on to the next step. A name given with -p takes precedence over this entire order, and -p default can name the default profile explicitly.

To turn off both lookups, set the environment variable:

MOAI_NO_PROFILE_FALLBACK=1 moai cc    # ignore the record and run the default profile

The per-project record is written when you launch with -p, and it is updated as well when you switch profiles in the Web Console. The default profile (default) is never recorded.

Limitations to know

• Moving or renaming a project directory leaves the existing entry matching no path. The entry is skipped silently, so it does not break launching.
• The projects: map grows as projects accumulate, and there is no command to prune it yet.
• moai profile current reports the global record as-is. So in a project whose remembered profile differs from the global record, the name reported by moai profile current may differ from the profile that moai cc without -p actually launches.

A newly created profile directory does not yet contain .claude.json, the file that holds Claude Code’s account state. Account state is kept per configuration directory on every platform, so even when your existing session is perfectly healthy, the first launch with a new profile brings up the login / onboarding screen.

Note

The notice below ships in the next release. The current release (v3.0.1) moves to the login screen with no warning at all.

Before starting Claude Code, the launcher prints the following to standard error:

Notice: profile "work" has no Claude Code configuration yet.
  Claude Code will show the login / onboarding screen on this launch.
  Account state is not inherited between profiles; sign in once and it
  persists for this profile.

No credentials are copied or moved into the new profile. Where account state lives differs by platform, so a copy tailored to one platform would be wrong on another. Once you sign in, that state stays with the profile, so this screen does not appear on later launches.

When configuring a profile, you can select a model that supports a 1M context window. The [1m] suffix is not a separate model — it is Claude Code’s native context-window modifier.

Selectable model aliases:

• opus / opus[1m]
• sonnet / sonnet[1m]
• fable / fable[1m]

Select it in the “Model Settings” step of the setup wizard, or edit the profile settings file directly. 1M context models are well suited for analyzing large codebases or working with long documents.

• moai web Console - Switch and edit profiles from the browser
• CLI Reference - Full CLI commands
• Quick Start - Getting started
• Initial Setup - Project initialization