# How to Configure Custom Session Directories for Unsupported Agents in agentsview

> Configure custom session directories for unsupported agents in agentsview using environment variables or TOML arrays. Learn to manage data paths efficiently.

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

---

**You can configure custom session directories for unsupported agents in agentsview using environment variables for single-directory overrides, TOML arrays for multiple paths, or by relocating the entire data root via `AGENTSVIEW_DATA_DIR`.**

agentsview is an open-source session management tool that stores AI agent files under a centralized data directory. When working with custom agents or non-standard session storage locations, you can configure custom session directories for unsupported agents through flexible override mechanisms defined in the `kenn-io/agentsview` repository.

## Understanding the Configuration Architecture

The agentsview configuration system relies on the `AgentDef` struct defined in [`internal/parser/types.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go) (lines 46‑55). Each agent entry specifies an `EnvVar` field for environment-based overrides and a `ConfigKey` field for TOML configuration. During startup, the application loads directory paths through a cascading hierarchy: default values are initialized first, then overridden by the config file, then environment variables, and finally CLI flags.

The loading logic resides in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go), where the `loadEnv` function (lines 88‑94) processes per-agent directory overrides, and the TOML parsing logic (lines 78‑84) handles configuration file arrays.

## Method 1: Environment Variables for Single Directory Overrides

For quick redirection of a single agent's session storage, export the environment variable corresponding to the agent's `EnvVar` definition. This method immediately overrides the default path without modifying configuration files.

```bash
export AGENTSVIEW_DATA_DIR=$HOME/.agentsview          # Optional global root

export CLAUDE_PROJECTS_DIR=$HOME/my-claude-sessions   # Per-agent override

agentsview serve

```

As implemented in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 88‑94), the application replaces the default directory slice with the value of the matching environment variable. When `CLAUDE_PROJECTS_DIR` is set, agentsview reads sessions from your custom path instead of the default `$HOME/.claude/projects`.

## Method 2: TOML Configuration for Multiple Directories

To specify multiple search directories for an agent, use the TOML key defined in the `ConfigKey` field. Create or edit `$AGENTSVIEW_DATA_DIR/config.toml`:

```toml

# Per-agent directory overrides

claude_project_dirs = ["/data/claude1", "/data/claude2"]
codex_sessions_dirs = ["/data/codex", "/backup/codex-sessions"]

```

According to the parsing logic in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 78‑84), the configuration loader reads these arrays into `Config.AgentDirs[agent]`. The sync engine searches these paths in order when locating session files. This method is particularly useful for unsupported agents that require multiple session sources or specialized directory structures.

## Method 3: Global Data Directory Relocation

To change the storage location for all agents, databases, and internal files simultaneously, set the `AGENTSVIEW_DATA_DIR` environment variable (or the legacy `AGENT_VIEWER_DATA_DIR`):

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

```

This relocates the entire data root, including `sessions.db`, [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/config.toml), and default agent subdirectories, to the specified path. The global data directory resolution occurs in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 78‑86).

## Configuration Precedence Rules

Understanding the override hierarchy is critical when you configure custom session directories for unsupported agents:

1. **Defaults** - Hardcoded paths from [`internal/parser/types.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go)
2. **Config File** - Values from `$AGENTSVIEW_DATA_DIR/config.toml`
3. **Environment Variables** - Runtime env vars (highest priority for per-agent settings)
4. **CLI Flags** - Command-line arguments (final override)

**Important:** Environment variables take precedence over TOML configuration. If `CODEX_SESSIONS_DIR` is set in the environment, any `codex_sessions_dirs` entries in [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/config.toml) are ignored. This behavior is enforced during the `loadEnv` phase in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go).

## Summary

- **Environment variables** provide single-directory overrides via the `EnvVar` field defined in [`internal/parser/types.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go) (lines 46‑55)
- **TOML configuration** supports multiple directories through `ConfigKey` arrays parsed in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 78‑84)
- **Global relocation** uses `AGENTSVIEW_DATA_DIR` to move all data, as implemented in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 78‑86)
- **Precedence** follows: defaults → config file → environment → CLI flags
- **Restart required** - You must restart the agentsview server after any configuration change for the overrides to take effect

## Frequently Asked Questions

### How do I configure directories for a completely unsupported agent?

To configure custom session directories for unsupported agents not defined in [`internal/parser/types.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go), add custom entries to your [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/config.toml) file using the appropriate agent identifier as the configuration key. While unsupported agents won't have predefined `EnvVar` constants in the source code, you can still define directory arrays in TOML. For complete support, you may need to add a new `AgentDef` entry to [`internal/parser/types.go`](https://github.com/kenn-io/agentsview/blob/main/internal/parser/types.go) with the appropriate `EnvVar` and `ConfigKey` fields, then recompile.

### Why are my TOML configuration changes being ignored?

Your environment variables are overriding the TOML settings. As implemented in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 88‑94), environment variables take precedence over configuration file entries. Check for conflicting variables like `CLAUDE_PROJECTS_DIR` or `CODEX_SESSIONS_DIR` in your shell environment using `env | grep DIR`, and unset them to allow the TOML values to take effect.

### Can I use relative paths when configuring custom directories?

While agentsview accepts relative paths, absolute paths are strongly recommended when you configure custom session directories for unsupported agents. Relative paths are resolved against the working directory where `agentsview serve` is executed, which can cause inconsistencies if the service runs under different user contexts or systemd services.

### What is the difference between `AGENTSVIEW_DATA_DIR` and agent-specific overrides?

`AGENTSVIEW_DATA_DIR` sets the global root for all agentsview internal data, including the SQLite database, cache files, and the [`config.toml`](https://github.com/kenn-io/agentsview/blob/main/config.toml) file itself, as defined in [`internal/config/config.go`](https://github.com/kenn-io/agentsview/blob/main/internal/config/config.go) (lines 78‑86). Agent-specific directories (set via `EnvVar` or `ConfigKey`) only override where session files are read for that particular agent, while the database and other internal files remain under the global data directory.