Skip to main content
Use .capy/settings.json to configure repository-level behavior. Add the schema for autocomplete + validation: 
{
  "$schema": "https://capy.ai/settings.schema.json"
}

​
Basic setup

{
  "$schema": "https://capy.ai/settings.schema.json",
  "hooks": {
    "setup": ["pnpm install"],
    "terminals": [{ "name": "dev", "command": "pnpm dev" }],
    "previews": [{ "name": "app", "port": 3000 }]
  }
}

​
Setup hooks

Run once when the repository is initialized in a session. 
{
  "hooks": {
    "setup": ["pnpm install", "pnpm db:migrate"]
  }
}

​
Terminals

Persistent sessions that start automatically. 
{
  "hooks": {
    "terminals": [
      { "name": "dev", "command": "pnpm dev", "readonly": false },
      { "name": "logs", "command": "tail -f logs/app.log", "readonly": true }
    ]
  }
}

​
Previews

Preview URLs for running web services. 
{
  "hooks": {
    "previews": [
      { "name": "Frontend", "port": 3000 },
      { "name": "API", "port": 8080 }
    ]
  }
}

​
Tool hooks

Run commands before/after tool execution. 
{
  "hooks": {
    "tools": {
      "pre": {
        "bash_run": ["echo 'About to run command'"]
      },
      "post": {
        "edit": ["pnpm lint --fix ${file_path}"],
        "write": ["pnpm prettier --write ${file_path}"]
      }
    }
  }
}
Available tools: bash_run, edit, multi_edit, write, read, glob, grep.

​
Context

Control how hook output is added to agent context. 
{
  "hooks": {
    "context": {
      "maxOutputLength": 2000,
      "truncateStrategy": "tail"
    }
  }
}
PropertyTypeDefaultDescription
maxOutputLengthnumber2000Maximum characters of hook output to include
truncateStrategystringtailTruncation strategy: head, tail, middle

​
Full example

{
  "$schema": "https://capy.ai/settings.schema.json",
  "hooks": {
    "setup": ["pnpm install"],
    "terminals": [
      { "name": "dev", "command": "pnpm dev", "readonly": false },
      { "name": "tests", "command": "pnpm test:watch", "readonly": true }
    ],
    "previews": [{ "name": "app", "port": 3000 }],
    "tools": {
      "post": {
        "edit": ["pnpm lint --fix ${file_path}"],
        "multi_edit": ["pnpm lint --fix"]
      }
    },
    "context": {
      "maxOutputLength": 3000,
      "truncateStrategy": "tail"
    }
  }
}