# Configuration

All LogiCoal configuration files and their locations.

## User Configuration

These files live in your home directory and apply globally.

### `~/.coalcode/config.json`

Main configuration file. Managed automatically — you rarely need to edit this directly.

Contains:

- **Auth tokens** — Access token, refresh token, expiry
- **User info** — Name, email (cached from server)
- **Team info** — Team ID and name
- **API URL** — Defaults to `https://coals.ai`
- **Device ID** — Unique device identifier, generated on first run
- **Usage** — Plan name and remaining token balance
- **Dismissed alerts** — IDs of dismissed server alerts

To change the API URL:

```bash
logicoal config --api-url https://my-instance.example.com
```

### `~/.coalcode/commands/`

Custom slash command files. Each `.md` file becomes a `/command`.

See [Custom Commands](/content/docs/custom-commands/index.html).

### `~/.coalcode/agents/roles/`

Custom agent role definitions. Each `.md` file defines a role.

See [Custom Roles](/content/docs/custom-roles/index.html).

### `~/.coalcode/agents/memory/`

Persisted agent memories. JSON files, one per role. Managed automatically by the agent system.

View with `/memory <role>`. Clear with `/memory clear <role>`.

### `~/.coalcode/agents/history/`

Agent run history. JSON files named by date, ID, and role. Managed automatically.

View with `/history`.

### `~/.logicoal/mcp.json`

Global MCP server configuration. Applies to all projects.

See [MCP Integration](/content/docs/mcp/index.html).

## Project Configuration

These files live in your project directory and are project-specific.

### `.COAL.md`

AI-generated project documentation. Read automatically at the start of every session. Generated by `/init`.

See [Project Initialization](/content/docs/project-init/index.html).

### `.coals/mcp.json`

Project-local MCP server configuration. Servers defined here override global servers with the same name.

See [MCP Integration](/content/docs/mcp/index.html).

### `.coals/agents/`

Project-local custom agent roles. Override user-global roles of the same name.

See [Custom Roles](/content/docs/custom-roles/index.html).

### `.coals/` (workspace)

Workspace directory for plans, research, artifacts, prompts, and progress tracking. Created by `/init`.

See [Project Initialization](/content/docs/project-init/index.html).

## Summary Table

| Path | Purpose | Managed by |
| --- | --- | --- |
| `~/.coalcode/config.json` | Auth, API URL, device ID | Automatic |
| `~/.coalcode/commands/*.md` | Custom slash commands | User |
| `~/.coalcode/agents/roles/*.md` | Custom agent roles | User |
| `~/.coalcode/agents/memory/` | Agent memories | Automatic |
| `~/.coalcode/agents/history/` | Agent run history | Automatic |
| `~/.logicoal/mcp.json` | Global MCP servers | User / wizard |
| `.COAL.md` | Project documentation | `/init` + user edits |
| `.coals/mcp.json` | Project MCP servers | User / wizard |
| `.coals/agents/*.md` | Project agent roles | User (create manually) |
| `.coals/plans/` | Implementation plans | User |
| `.coals/research/` | Research notes | User |
| `.coals/artifacts/` | Generated snippets | User |
| `.coals/prompts/` | Saved prompts | User |
| `.coals/progress/` | Progress tracking | User |
| `.agents/plan/` | Agent plan output | Agents |