# Configuration

The core package manages all runtime configuration through a combination of a YAML config file and an embedded SQLite database. The config file lives at `~/.config/agent-smith/config.yml` on Linux, `%APPDATA%/agent-smith/config.yml` on Windows, or `~/Library/Application Support/agent-smith/config.yml` on macOS.

## Configuration File

The configuration file (`config.yml`) defines inference backends, feature search paths, plugins, agent settings, workspaces, and optional prompt file/data directory paths:

```yaml
backends:
  default: llamacpp
  llamacpp:
    type: llamacpp
    url: http://localhost:8080/v1
  openai:
    type: openai
    url: https://api.openai.com/v1
    apiKey: "sk-..."
features:
  - ~/path/to/features
plugins:
  - @agent-smith/feat-shell
workspaces:
  project-a: /home/user/projects/a
agents:
  mybot:
    model: qwen35b
    top_k: 20
    top_p: 0.85
    min_p: 0
    temperature: 0.6
    repeat_penalty: 1
    presence_penalty: 1.5
    backend: llamacpp
    chat_template_kwargs:
      enable_thinking: true
      preserve_thinking: true
    props:
      propagateModel: true # use this model and backend for all subagents
      propagateInferParams: true # use these inference params for all subagents
```

## Configuration Loading

The `conf` module exports several functions for managing configuration:

### `processConfPath(confPath: string)`

Parses the YAML config file and upserts all configuration into the SQLite database. Returns an object with discovered paths, prompt file path, and data directory path.

```typescript
import { conf } from "@agent-smith/core";

const { paths, pf, dd } = await conf.processConfPath("~/.config/agent-smith/config.yml");
// paths: Array<string> — all feature search paths
// pf: string — prompt file path
// dd: string — data directory path
```

This function handles:
- **Backends**: Creates `InferenceBackend` objects from the `backends` section, marks the default backend, and calls `upsertBackends()` to store them in the `backend` table
- **Feature paths**: Inserts each path from the `features` array into the `featurespath` table
- **Plugins**: Resolves npm plugin paths via `npm root -g`, inserts them into the `plugin` table
- **Agent settings**: Reads per-agent inference parameters (model, temperature, max_tokens, etc.) and upserts them into the `agentsettings` table
- **Workspaces**: Upserts workspace entries into the `workspace` table

### `createConfigFileIfNotExists(cfp?: string)`

Creates a default config file if none exists at the given path (or the default location). The default includes an `llamacpp` backend pointing to `http://localhost:8080/v1`.

```typescript
import { conf } from "@agent-smith/core";

const fp = conf.createConfigFileIfNotExists();
// Returns: string — the config file path
```

### `updateConfigFile(conf: ConfigFile, cfp?: string)`

Updates an existing config file with new YAML content. Throws if the file does not exist.

```typescript
import { conf } from "@agent-smith/core";

conf.updateConfigFile({
  backends: { default: "openai", openai: { type: "openai", url: "https://api.openai.com/v1" } },
  promptfile: ""
});
```

### `getConfigPath(appName: string, filename: string)`

Returns the configuration directory and database path for a given application name. Uses platform-specific conventions.

```typescript
import { conf } from "@agent-smith/core";

const { confDir, dbPath } = conf.getConfigPath("agent-smith", "config.db");
// confDir: "~/.config/agent-smith"
// dbPath: "~/.config/agent-smith/config.db"
```

## Backend Configuration

Inference backends are stored in the `backend` SQLite table with columns: `name`, `type` (`browser` or `openai`), `url`, `isdefault`, and `apiKey`. The default backend is marked with `isDefault: true` and serves as the fallback when no agent-specific backend is configured.

```typescript
import { state } from "@agent-smith/core";

// List all backends
const backends = state.listBackends();

// Set the default backend
await state.setBackend("openai");
```

## Feature Paths Management

Feature search paths are registered in the `featurespath` table. Each path is scanned during feature discovery. The `updateFeaturesCmd` function reads all registered paths (including plugin paths), scans the filesystem, and updates the database.

```typescript
import { conf } from "@agent-smith/core";

// Re-scan all registered feature paths
await conf.updateFeaturesCmd({});
```

## Plugin Management

Plugins are npm packages installed globally. Their `dist` directory under `npm root -g/<plugin>/dist` is added to the feature search paths. Plugins are registered in the `plugin` table with `name` and `path`.

The `buildPluginsPaths` function resolves plugin paths from the config's `plugins` array:

```typescript
import { buildPluginsPaths } from "@agent-smith/core/state/plugins";

const plugins = await buildPluginsPaths(["my-plugin", "another-plugin"]);
// Returns: Array<{ name: string, path: string }>
```

## SQLite Integration with CLI

The `lm conf <path>` CLI command triggers the full configuration pipeline:

1. Initializes the database
2. Reads or creates the config file
3. Calls `processConfPath()` to upsert backends, feature paths, plugins, and agent settings
4. Calls `updateAllFeatures()` to scan all paths and register features

```bash
lm conf ~/.config/agent-smith/config.yml
```

The `lm update` command re-scans features without reloading the config:

```bash
lm update
```

## Agent Settings

Per-agent inference settings are stored in the `agentsettings` table with columns for model, sampling parameters (max_tokens, top_k, top_p, min_p, temperature, repeat_penalty, presence_penalty, frequency_penalty), backend, and additional kwargs. These are loaded into the reactive `agentSettings` object on first access.

```typescript
import { state } from "@agent-smith/core";

const settings = state.getAgentSettings();
// Returns: Record<string, AgentSettings>
```

<a href="javascript:openLink('/libraries/core/feature-discovery')">Next: Feature Discovery</a>