# How to Configure Custom Agent Session Directories in agentsview

> Learn how to configure custom agent session directories in agentsview using environment variables or TOML. Easily manage your application data for agentsview.

- Repository: [Kenn Software/agentsview](https://github.com/kenn-io/agentsview)
- Tags: how-to-guide
- Published: 2026-06-12

---

**You can configure custom agent session directories in agentsview using environment variables for single-directory overrides, TOML configuration arrays for multiple directories, or by changing the global `AGENTSVIEW_DATA_DIR` to relocate all application data.**

agentsview stores session files for each supported AI agent under a configurable data directory structure. By default, the application looks for sessions in per-agent subdirectories, but you can override these locations to support custom workflows, multiple project roots, or external storage systems. This guide leverages the actual source code from the kenn-io/agentsview repository to show you exactly how these mechanisms work.

## Understanding the Configuration Hierarchy

According to the source code in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go), agentsview loads configuration in a strict order: **defaults** first, then the **TOML configuration file**, followed by **environment variables**, and finally **CLI flags**. The final directory list for each agent is stored in `Config.AgentDirs[agent]` and used by the sync engine and file-watcher. This hierarchy means that environment variables always win over configuration file settings.

## Method 1: Environment Variables for Single-Directory Overrides

Environment variables provide the highest precedence for configuring individual agent directories. In [`internal/parser/types.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go) (lines 46-55), each agent definition includes an `EnvVar` field that maps to a specific environment variable name.

When the `loadEnv` function runs in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 88-94), it replaces the default directory slices with the value of the matching environment variable. This method supports only a single directory per agent.

```bash
export CLAUDE_PROJECTS_DIR=/my/custom/claude/projects
export CODEX_SESSIONS_DIR=/my/codex/sessions
agentsview serve

```

## Method 2: TOML Configuration for Multiple Directories

To specify multiple directories for a single agent, use the TOML configuration file. The mapping between configuration keys and agents is defined in the `ConfigKey` field of [`internal/parser/types.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go) (lines 46-55).

The file-parsing logic in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 78-84) reads these keys as arrays. Create or edit `$AGENTSVIEW_DATA_DIR/config.toml`:

```toml
claude_project_dirs = ["/data/claude/work", "/data/claude/personal"]
codex_sessions_dirs = ["/data/codex", "/backup/codex"]

```

If an environment variable is set for an agent, the TOML values are ignored for that specific agent.

## Method 3: Global Data Directory

To change the location of all agentsview data—including the database, settings, and session files—set the `AGENTSVIEW_DATA_DIR` environment variable. This is processed in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 78-86). The legacy variable `AGENT_VIEWER_DATA_DIR` is also supported for backwards compatibility.

```bash
export AGENTSVIEW_DATA_DIR=/mnt/agentsview-data
agentsview serve

```

This relocates `sessions.db`, [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/config.toml), and all agent subdirectories to the specified path.

## Complete Configuration Examples

### Override a Single Agent via Environment Variable

```bash
export AGENTSVIEW_DATA_DIR=$HOME/.agentsview
export CLAUDE_PROJECTS_DIR=$HOME/my-claude-sessions
agentsview serve

```

Claude sessions will be read from `$HOME/my-claude-sessions` instead of the default `$HOME/.claude/projects`.

### Provide Multiple Directories via config.toml

Create `$HOME/.agentsview/config.toml`:

```toml
claude_project_dirs = ["/data/claude1", "/data/claude2"]
codex_sessions_dirs = ["/data/codex"]

```

Restart agentsview to search these paths in order for session files.

### Combine Environment and Config File

```bash
export CODEX_SESSIONS_DIR=/my/codex
agentsview serve

```

Even if `codex_sessions_dirs` is defined in [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/config.toml), Codex will only use `/my/codex` because the environment variable takes precedence.

### Change the Global Data Directory

```bash
export AGENTSVIEW_DATA_DIR=/mnt/agentsview-data
agentsview serve

```

All internal files are now stored under `/mnt/agentsview-data`.

## Summary

- **Environment variables** (e.g., `CLAUDE_PROJECTS_DIR`) override single agent directories and take precedence over all other methods, as implemented in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) lines 88-94.
- **TOML configuration** supports multiple directories per agent via array syntax (e.g., `claude_project_dirs = ["/path1", "/path2"]`), parsed in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) lines 78-84.
- **Global data directory** (`AGENTSVIEW_DATA_DIR`) relocates the entire application data root, including the config file and database.
- Configuration loads in the order: defaults → config file → environment → CLI flags.
- Restart the server after any configuration change for it to take effect.

## Frequently Asked Questions

### Can I use both environment variables and the config.toml file together?

Yes, but environment variables take precedence. If you set `CLAUDE_PROJECTS_DIR` in your shell, any `claude_project_dirs` entries in [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/config.toml) are ignored according to the loading logic in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go). Use environment variables for temporary overrides and TOML for persistent multi-directory configurations.

### Where does agentsview store its configuration file?

By default, agentsview looks for [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/config.toml) inside the directory specified by `AGENTSVIEW_DATA_DIR`. If unset, this defaults to a system-specific user data directory (typically `$HOME/.agentsview` on Unix systems). You can verify the exact path by checking the startup logs or setting `AGENTSVIEW_DATA_DIR` explicitly.

### How do I configure multiple directories for a single agent?

Use the TOML configuration file with array syntax. For example, set `claude_project_dirs = ["/work/projects", "/personal/projects"]` in your [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/config.toml). Environment variables only support single directory values, as defined in the `AgentDef` struct in [`internal/parser/types.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go).

### Why is my config.toml change not taking effect?

Ensure you have restarted the agentsview server after saving the file. Also, verify that no environment variable is overriding the specific agent configuration, as environment variables take precedence over TOML settings according to the hierarchy in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go).