# Files and environment variables

## In a repository

| Path | Versioned? | Purpose |
|---|---|---|
| `.oak/` | — | The local repository: its database (`.oak/oak.db`), in-progress merge state, and hooks. Never committed, except the files below. |
| `.oak/workflows/*.yml` | Yes | [CI workflows](/docs/ci-workflows). |
| `.oak/PERMISSIONS` | Yes | [Path permissions](/docs/path-permissions), read from `main`. |
| `.oak/attributes` | Yes | Reserved for per-path attributes. |
| `.oak/hooks/pre-commit`, `post-commit` | No | Local [hooks](/docs/making-changes#hooks). |
| `.oakignore` | Yes | Files Oak should ignore, in `.gitignore` syntax. |
| `.gitignore` | Yes | Used **only** when there's no `.oakignore`. |
| `AGENTS.md`, `CLAUDE.md` | Yes | Instructions for coding agents; `oak init` offers to write them. |
| `.claude/skills/oak-vcs/` | Yes | The agent skill, from `oak skill install`. |
| `.oak-space` | — | Marks the root of an [agent space](/docs/spaces). |

## In your home directory

| Path | Purpose |
|---|---|
| `~/.local/bin/oak` | The CLI, where the installer puts it. |
| `~/.oak/credentials` | Saved logins, one per server (from `oak login`). |
| `~/.oak/mounts/` | Mount state and caches. Override with `OAK_MOUNTS_ROOT`. |
| `~/.oak/version_check` | When the CLI last checked for an update. |
| `~/.oak/feedback.json` | The contact email `oak feedback` remembers. |
| `~/oaktree/` | The default parent directory for mounts. |
| `~/.claude/skills/oak-vcs/` | The agent skill, from `oak skill install --global`. |

## Environment variables

`oak environment` (or `oak env`) prints every variable below with its effective value — secrets as set/unset only.

### Server and credentials

| Variable | Effect |
|---|---|
| `OAK_REMOTE` | Server URL for this invocation, overriding the checkout's linked server. |
| `OAK_API_KEY` | Token to authenticate with. Beats every stored credential. See [API keys](/docs/api-keys). |
| `OAK_REPO` | `org/repo` to link on a first push — the same as `oak push --repo`. |
| `OAK_SERVE_TOKEN` | Bearer token for `oak serve`. |

### Identity

| Variable | Effect |
|---|---|
| `OAK_AUTHOR` | Author name on commits, and the prefix of generated branch names. Defaults to your login, then `USER` / `USERNAME`. |
| `OAK_EMAIL` | Contact email for `oak feedback`. |

### Network

| Variable | Effect |
|---|---|
| `OAK_NO_UPDATE_CHECK` | Turn off the daily check for a new CLI version. |
| `OAK_UPLOAD_CONCURRENCY` | Parallel uploads during push. |
| `OAK_DOWNLOAD_CONCURRENCY` | Parallel downloads during clone and pull (default 32). |
| `OAK_PROBE_TIMEOUT_SECS` | Timeout for server probes, 1–300 (default 20). |
| `OAK_ALLOW_PARTIAL_CLONE` | Recovery only: skip files a broken server can't send instead of failing. |
| `HTTPS_PROXY`, `HTTP_PROXY`, `ALL_PROXY`, `NO_PROXY` | Standard proxy settings (lowercase forms too). |

### Mounts

| Variable | Effect |
|---|---|
| `OAK_MOUNTS_ROOT` | Where mount state lives (default `~/.oak/mounts`). |

### Output

| Variable | Effect |
|---|---|
| `OAK_VERBOSE` | Print per-phase timings, like `--verbose`. |
| `OAK_LOG` | Log filter for debugging (for example `OAK_LOG=debug`). |
| `OAK_PROGRESS` | `always`, `never`, or `auto` progress display. |
| `OAK_SPINNER` | Spinner style: `line`, `pulse`, `arc`, `minimal`, `oak`. |
| `NO_COLOR`, `CLICOLOR_FORCE` | Disable or force color. |
| `CI` | When set, progress display is off by default. |

### Tools

| Variable | Effect |
|---|---|
| `OAK_DIFF_TOOL` | External program to use instead of `oak diff`'s viewer. |
| `PAGER` | Pager for long output. |
| `VISUAL`, `EDITOR` | Editor for `oak feedback` and `oak split` (falls back to `vi`). |

### Set by Oak

| Variable | Where |
|---|---|
| `OAK_HOOK` | In [hooks](/docs/making-changes#hooks): the event name. |
| `OAK_CI_RUN_ID`, `OAK_CI_COMMIT` | In [CI steps](/docs/ci-workflows#environment-variables-in-every-step). |

### Installer

| Variable | Effect |
|---|---|
| `INSTALL_DIR` | Where `install.sh` / `install.ps1` put the binary. |
| `OAK_NO_LOGIN` | Skip the installer's login prompt. |