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

All Tarsk data lives under the application support directory:

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

Override with --data-dir, --assets-dir, or these environment variables:

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}/	One directory per thread, each a full git clone (numeric suffix on conflict)
port.json	Active server port (written on server start)
tarsk-logs.txt	Verbose log output (--debug or Settings → Settings → Logging)

Settings such as provider API keys, enabled models, UI preferences, and onboarding state are stored in the database, not in JSON config files.

Agent Configuration Files

Tarsk uses .agents/ directories for skills, rules, commands, subagents, and MCP configuration. These are markdown files with YAML frontmatter.

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	(via Settings UI)	.agents/mcp.json or mcp.json
AGENTS.md	(via Settings UI)	Project root (AGENTS.md)

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

Skill Frontmatter

---
name: my-skill
description: What this skill does (used for auto-activation)
license: MIT
compatibility: Node.js 18+
allowed-tools: Bash(git *)
when-to-use: Extra matching keywords
disable-model-invocation: false
---

Field	Required	Description
name	Yes	Must match directory name. 1-64 chars, lowercase + hyphens
description	Yes	Used for keyword-based auto-activation (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	Additional auto-activation keywords
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	Yes	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
argumentHint: focus area
mode: plan
---

Field	Required	Description
description	Yes	Shown in the autocomplete dropdown
argumentHint	No	Placeholder text for user input after the command name
mode	No	default or plan (activates plan mode on use)
action	No	Built-in action to execute instead of inserting prompt

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	List of subagents this agent can invoke
model	No	Model override for this agent
provider	No	Provider override for this agent
user-invocable	No	Whether the user can invoke directly (default: true)
disable-model-invocation	No	Hide from agent picker (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[]	No	Command arguments
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 server
cwd	string	No	Working directory
timeout	number	No	Startup timeout in milliseconds

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_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 (with BETTERSTACK_SOURCE_TOKEN)

CLI Flags

Flag	Description
--server	Start the API server only (do not open a browser tab)
--debug	Enable verbose logging (written to tarsk-logs.txt)
--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. Keys are stored in the database, not in config files.

Debug logs: Run with npx tarsk --debug, or enable Logging in Settings → Settings, to write verbose logs to ~/Library/Application Support/Tarsk/tarsk-logs.txt.

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