Configuration Reference

Tarsk stores settings in a local SQLite database and uses markdown files for agent configuration. This reference covers every configuration surface.

Data Directory

Tarsk stores its database and managed workspace folders under the application support directory:

Platform	Default path
macOS	~/Library/Application Support/Tarsk/
Linux / Windows (CLI)	Same path under your home directory

Use TARSK_APP_SUPPORT_DIR to change the application support root, or --data-dir / TARSK_DATA_DIR to change the data directory. Use --assets-dir / TARSK_ASSETS_DIR for companion assets; this does not move application data.

Variable	Description
TARSK_APP_SUPPORT_DIR	Root application support directory
TARSK_DATA_DIR	Data directory (defaults to <appSupport>/data)
TARSK_ASSETS_DIR	Companion assets next to the compiled server binary

Contents:

File / Directory	Purpose
data/tarsk.db	SQLite database (projects, threads, settings, conversation history)
data/{repo-slug}/	Managed clones or copies (numeric suffix on conflict)
port.json	Active server port (written on server start)

Tarsk stores provider API keys, enabled models, and onboarding state in the database. It also mirrors provider keys to .env in the server’s working directory. The frontend stores appearance preferences in browser local storage. Tarsk stores the server bind mode in data/server-bind-mode.json.

Agent Configuration Files

Tarsk uses .agents/ directories for skills, rules, commands, subagents, and MCP configuration. Write skills, rules, commands, and subagents as Markdown files with YAML frontmatter. Use JSON for MCP configuration.

File Locations

Item	Global (all projects)	Project-level (per repo)
Skills	~/.agents/skills/	<threadPath>/.agents/skills/
Rules	~/.agents/rules/	<threadPath>/.agents/rules/
Slash Commands	~/.agents/commands/	<threadPath>/.agents/commands/
Subagents	~/.agents/agents/	<threadPath>/.agents/agents/
MCP Config	None (project-level only)	.agents/mcp.json or mcp.json
AGENTS.md	Not exposed in Settings	Selected thread root (AGENTS.md)

Project-level files override global files with the same name.

Skill Frontmatter

---
name: my-skill
description: What this skill does (shown in the skill catalog)
license: MIT
compatibility: Node.js 18+
allowed-tools: Bash(git *)
when_to_use: Guidance on when to use this skill
disable-model-invocation: false
---

Field	Required	Description
name	Yes	Must match directory name. 1-64 lowercase letters, digits, or hyphens; no leading, trailing, or consecutive hyphens
description	Yes	Description in the model’s skill catalog (1-1024 chars)
license	No	License identifier
compatibility	No	System requirements text
allowed-tools	No	Restricts which tools and shell commands the skill can use
when_to_use	No	Usage guidance in the model’s skill catalog
disable-model-invocation	No	When true, only activates via explicit /skill-name

Rule Frontmatter

---
description: What this rule enforces
alwaysApply: false
---

Field	Required	Description
description	No	Tells the agent when to consult the rule
alwaysApply	No	true = full content always in context; false = on-demand

The rule name is derived from the filename (e.g. coding-standards.md becomes coding-standards).

Slash Command Frontmatter

---
description: What this command does
argument-hint: focus area
mode: plan
---

Field	Required	Description
description	No	Description in the autocomplete dropdown
argument-hint	No	Placeholder text for user input after the command name
mode	No	plan, ralph, or orchestrate (activates that chat mode when the command runs)
action	No	Internal metadata for built-in commands; the Markdown parser ignores this field

Subagent Frontmatter

---
name: code-reviewer
description: Review code for quality
tools: read grep
agents: [security-auditor]
model: gemini-2.5-flash
provider: google
user-invocable: true
disable-model-invocation: false
---

Field	Required	Description
name	Yes	Must match directory name
description	Yes	Shown in the agent picker
tools	No	Space-separated list of allowed tools
agents	No	Parsed metadata; does not restrict nested invocation
model	No	Model override for this agent
provider	No	Provider override for this agent
user-invocable	No	Parsed metadata; does not control invocation
disable-model-invocation	No	Exclude from the model’s subagent catalog and tool (default: false)

MCP Configuration

MCP servers are configured in .agents/mcp.json (preferred) or mcp.json (fallback) at the project root. Both servers and mcpServers root keys are accepted.

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
      "env": {
        "ALLOWED_DIRECTORIES": "/Users/username/projects"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/db"
      }
    }
  }
}

Remote MCP Servers

{
  "servers": {
    "zapier": {
      "url": "https://mcp.zapier.com/api/v1/connect?token=YOUR_TOKEN",
      "transport": "streamableHttp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Field	Type	Required	Description
command	string	For stdio	Command to start a local server
args	string[]	For stdio	Command arguments; use [] for none
url	string	For remote	Remote server URL (SSE or Streamable HTTP)
transport	string	No	"sse" or "streamableHttp"
headers	object	No	HTTP headers for remote requests
env	object	No	Environment variables for the local stdio process
timeout	number	No	Accepted in configuration; the MCP client does not apply it

CLI Environment Variables

Variable	Description
PORT	Server port in normal mode (default: 641). Ignored when --debug is set.
MODE	Set to development for dev server behavior (used by cli web script)
LOCAL_API_URL	Override the Local provider API URL (default: http://127.0.0.1:8000/v1)
LOCAL_API_KEY	API key for the Local provider
TARSK_DEBUG	Set to 1 for extra debug logging (disabled during tests)
TARSK_MICROCOMPACT	Set to false to disable microcompact token compression
TARSK_SUPERSESSION_PRUNING	Set to false to keep superseded tool results in model request context
TARSK_CONTENT_ADDRESSED_OBSERVATIONS	Set to false to disable content-addressed tool observations
MCP_OAUTH_CALLBACK_PORT	Port for MCP OAuth callback (auto-selected if unset)
BETTERSTACK_SOURCE_TOKEN	Better Stack log source token (with BETTERSTACK_INGESTING_HOST)
BETTERSTACK_INGESTING_HOST	Better Stack ingest host — allowlisted (in.logs.betterstack.com or *.betterstack.com / *.betterstackdata.com), paired with BETTERSTACK_SOURCE_TOKEN

CLI Flags

Flag	Description
--server	Start the API server only (do not open a browser tab)
--debug	Enable verbose logging
--data-dir	Override the data directory
--assets-dir	Override companion assets path
--port	Server port (sets PORT)
--open	Open the browser even when --server is set

Debug mode runs the server on port 462 instead of 641.

Troubleshooting

Missing API keys: Configure provider keys in Settings > Providers. Tarsk stores keys in the database and mirrors keys with a provider environment variable to .env in the server’s working directory.

Debug logs: Run with npx tarsk --debug, or enable Logging in Settings → Settings, to raise log verbosity. View recent entries in Settings → Logs.

Reset onboarding: Triple-click the Settings item in the settings sidebar to re-run the onboarding wizard.