--- title: ".xedant Folder" id: "657" type: "page" slug: "xedant-folder" published_at: "2026-06-04T17:02:46+00:00" modified_at: "2026-09-21T01:36:28+00:00" url: "https://xedant.com/agents/agent/docs/xedant-folder" markdown_url: "https://xedant.com/agents/agent/docs/xedant-folder.md" excerpt: "The .xedant/ folder is the configuration and data directory for Xedant Agent. It is created…" --- # .xedant Folder [https://xedant.com/agents/agent/docs/xedant-folder.md](https://xedant.com/agents/agent/docs/xedant-folder.md) ## What Is the .xedant Folder? The `.xedant/` folder is the configuration and data directory for Xedant Agent. It is created automatically in the root of your project the first time Xedant Agent runs, and it stores everything the application needs: build definitions, deployment settings, model presets, database files, run logs, and more. ![Screenshot showing the file structure inside the .xedant configuration folder](https://xedant.com/wp-content/uploads/2026/06/xedant-folder-content-v4.png) You will rarely need to edit these files yourself. The AI model reads `.xedant/README.md` to understand the format of every configuration file, so you can simply ask for changes — “add a build that runs my linter”, “set up a Docker deployment to staging”, “create a new model for GPT-4” — and the model will get the YAML syntax and file structure right. This page explains what each file and folder does, so you know what is inside them and can make informed decisions when the AI proposes changes. ## project.yml This is your project’s “ID card”. It stores the project name, an optional icon, and an optional link that opens the project in the VS Code web editor. ``` project: name: "MyProject" # Project name (auto-detected from git) icon: ".xedant/project.svg" # Path to project icon (optional) code: "https://..." # VSCode Web URL (optional) ``` The `name` field is set automatically from your git remote on the first run, so you usually do not need to change it. The `icon` field can point to an `.svg` or `.ico` file. The `code` field is used when you want a button in the interface that opens your project directly in VS Code. ## build.yml This is where you define automatic build checks — commands that verify whether the AI changed the code correctly. Despite the name, a build does not have to compile anything. Any command that produces a readable result — errors and warnings — works: compilers, linters (tools that check code style and mistakes), type checkers, test runs, security scanners, or your own check scripts. Builds come in two types: - **Command builds** run a command and parse its output, looking for errors and warnings - **Prompt builds** start a new chat with a review task — handy for code review and checks where the AI needs to “think” ``` build: compile: path: "server/" command: "dotnet build" delay: 3 timeout: 60 watch: "*.cs" ignore: [] replacements: [] stopStrings: [] display: always autofix: always startSound: "" endSound: "" soundVolume: 1.0 ai-review: watch: chat prompt: "/verify Review the recent code changes. Read the chat transcript at {chat} and report any problems." chatTitle: "Code Review" delay: 5 timeout: 120 ``` The key properties: - **command** — The shell command to run (command builds only) - **prompt** — The validation prompt sent to a new AI chat (prompt builds only) - **watch** — File name patterns (`*.ts *.js`), names of other builds (`compile`), or `chat` to run when a user chat completes - **delay** — Seconds to wait before starting after a change is detected (default: 3) - **timeout** — Maximum run time in seconds (default: 60) - **display** — When to show the build in the build panel: `always`, `errors`, `warnings`, or `never` - **autofix** — When to take part in AutoFix: `always`, `errors`, `warnings`, or `never` - **ignore** — Regex patterns to suppress from the error/warning output - **replacements** — find/replace pairs for paths in the output (useful when a build runs in Docker or temporary directories) - **stopStrings** — Strings that abort the build immediately when found in the output - **startSound / endSound / soundVolume** — Optional audio feedback when a build starts or finishes Builds can follow one another: one build watches another and starts only after it finishes successfully. This is how you chain checks — for example, compile → tests → deploy. Output is saved in `.xedant/build/` as three files per task: `{name}.output.txt` (full output), `{name}.errors.txt` (parsed errors), and `{name}.warnings.txt` (parsed warnings). [Learn more about builds, AutoFix, and the build panel →](/agents/agent/docs/build-deploy) ## deploy.yml This file defines deployment targets — how your application gets started once the builds pass. It supports two methods: **debug** for local development and **docker** for remote container deployments. ``` # Local development — runs directly on your computer deploy: my-app: method: "debug" path: "./server" command: "dotnet run" watch: "compile" # Restarts after this build completes successfully shallowCopy: true # Copy only changed files (faster) url: "https://..." # Optional: clickable link in the interface startSound: "" endSound: "" # Remote deployment — ships to a Docker container over SSH deploy: production: method: "docker" host: "server.com" username: "deploy" sshKeyPath: "~/.ssh/key" imageName: "app:latest" containerName: "myapp" dockerfilePath: "./Dockerfile" environmentVariables: - PORT=3000 portMappings: "8080": "3000" ``` The **debug** method runs the application right on your computer — convenient during development. It can watch builds and restart after a successful check, it copies only the files that changed (so restarts are faster), and it supports environment variables. The **docker** method sends the code to a remote server over SSH, builds a Docker image, and manages the container — for staging and production. Port and volume (folder) mapping, Docker networks, health checks, and custom build arguments are all supported. Output from the running application is saved to `.xedant/deploy/{name}.log`. Both methods support optional sound notifications (`startSound`, `endSound`, `soundVolume`). [Learn more about deployment controls, the deploy panel, and deployment methods →](/agents/agent/docs/build-deploy) ## models.yml This file stores your AI model presets. Each model defines a set of variables that are applied when you select that model in the interface — for example, the model identifier, context length, and pricing. ``` models: claude-sonnet: variables: - ANTHROPIC_MODEL=claude-sonnet-4-20250514 - MODEL_CONTEXT_LENGTH=200000 - MODEL_INPUT_PRICE=3.0 - MODEL_OUTPUT_PRICE=15.0 claude-sonnet-fast: variables: - ANTHROPIC_MODEL=claude-sonnet-4-20250514 - MODEL_CONTEXT_LENGTH=200000 - MODEL_INPUT_PRICE=3.0 - MODEL_OUTPUT_PRICE=15.0 ``` Models support **inheritance**: a child model takes over all the variables of its parent. For example, if you have the models `glm`, `glm-5`, and `glm-5-turbo`, the turbo variant inherits settings from both, and you only need to set what differs at each level. Values prefixed with `$` refer to system environment variables: `$MY_API_KEY` will be replaced with the value of the `MY_API_KEY` environment variable from your system. [Learn more about creating and switching models →](/agents/agent/docs/models) ## mcp.yml This is where you connect **MCP servers** — external tools that extend what the model can do: browsing web pages, querying databases, searching code, and more. (MCP stands for Model Context Protocol, a standard way to plug external tools into AI assistants.) ``` version: "1.0" servers: filesystem: enabled: true type: "stdio" command: "npx" args: - "-y" - "@modelcontextprotocol/server-filesystem" - "/project" env: NODE_ENV: "production" ``` Each server connects in one of three ways: - **stdio** — runs as a program on your computer - **http** — connects to a remote server over the internet - **sse** — connects through Server-Sent Events (the server itself sends updates) This file **syncs automatically** with Claude Code’s own MCP configuration on startup and whenever changes are detected, so you can manage servers either from the Xedant Agent settings interface or directly in the Claude Code configuration — they stay in sync. [Learn more about adding and managing MCP servers →](/agents/agent/docs/mcp-servers) ## hooks.yml This file defines **hooks** — rules that intercept the AI’s actions before they run. Use them to block dangerous operations or to run your own commands at the right moments. ``` PreToolUse: Bash: - type: "deny" pattern: "rm -rf /" message: "Dangerous command blocked" - type: "execute" pattern: "git push" command: "echo 'Push detected'" regex: false ``` There are two hook event types: - **PreToolUse** — fires before any AI action (a terminal command, a file edit, and so on). You can `deny` (block) matching operations — with a message to the agent — or `execute` (run) your own command when the pattern matches - **UserPromptSubmit** — fires when a prompt is submitted, letting you pre-process it The `hooks.yml` file **automatically generates** `.claude/settings.local.json` — the actual hooks configuration that Claude Code reads. This means you only maintain `hooks.yml`, and the matching Claude Code settings file updates automatically. [Learn more about deny rules, execute commands, and tool-use control →](/agents/agent/docs/hooks) ## skills.yml This file controls which **skills** are active in your project and what color each one shows in the interface. Skills are reusable sets of instructions that change how the AI behaves for specific tasks. ``` skills: version: "1.0" settings: skill-name: color: "#3b82f6" # Hex color for UI display (default: "#888888") ``` Each skill entry sets an optional `color` used to display it in the interface; the file is edited in the skills dialog and synced back automatically. The list of keys also forms the set of activated skills offered by the `/skill` command in the Telegram bot. [Learn more about using, creating, and editing skills →](/agents/agent/docs/skills) ## providers.yml This file stores the **AI provider definitions** — pre-configured templates that describe how to connect to different AI services. Each provider defines connection fields (API keys, base URLs) and a set of models with pre-configured variables such as pricing and context length. ``` providers: - name: anthropic displayName: Anthropic description: Direct access to Claude models by Anthropic icon: anthropic color: "#D4A574" harnesses: [claude-code, opencode, pi] modelEnv: ANTHROPIC_MODEL fields: - name: apiKey label: API Key env: ANTHROPIC_API_KEY type: secret default: "$ANTHROPIC_API_KEY" models: - value: claude-sonnet-5 label: Claude Sonnet 5 description: Best balance of speed and intelligence sets: ANTHROPIC_MODEL: "claude-sonnet-5" MODEL_INPUT_PRICE: "2" MODEL_OUTPUT_PRICE: "10" MODEL_CONTEXT_LENGTH: "1000000" ``` This file is created automatically from a built-in resource when it is missing. It ships with pre-configured providers for popular services such as Anthropic, OpenRouter, and others. You rarely need to edit it by hand — the model wizard in the interface uses these definitions to set up a connection. ## Parser Files Three parser files pull errors and warnings out of the text output of programs. They all work the same way — a simple rule system with `[ERROR]` and `[WARNING]` blocks containing search patterns (regular expressions) inside. The files are thoroughly documented with comments inside, so you almost never need to edit them by hand. ### How the Parsers Work The parser walks the output lines and tries the patterns one by one: - **Comment lines** starting with `#` are ignored (they are used for documentation) - **Single-line patterns** — match one line of output - **Multi-line patterns** — wrapped in `{{...}}`, capture one or more consecutive lines (handy for detailed error reports or indented context) ``` # TypeScript compilation errors [ERROR] .*\.ts.* # Matches a line containing a .ts file path Error.* # Matches a line starting with "Error" {{^\s+}} # Matches the indented context lines that follow [/ERROR] ``` Parsers reload automatically when their files change — edits take effect immediately. ### build.parser Extracts errors and warnings from **build command output**. It already ships with patterns for C# (MsBuild, CSC), TypeScript, Svelte, Vite, Python (ruff), and ReSharper — add patterns for your project’s other tools as needed. ### deploy.parser Pulls errors and warnings from **running application logs**: unhandled exceptions, detailed error reports, database connection failures, HTTP errors, and crashes across different platforms. ### output.parser A general-purpose parser for **plain script output**: command-line errors, Python error reports, Node.js and npm failures, and other common formats. It is used when the output belongs neither to a build nor to a deployment. ## license.txt This file stores your **application license key** as a Base64-encoded JSON string. It has the highest priority of all license sources — it overrides both the `--license` command-line argument and the `AGENT_LICENSE` environment variable. If this file is present, its content is used regardless of any other configuration. [Learn more about license types, activation, and status →](/agents/agent/docs/licensing) ## project.db This is the **application database** that stores all persistent Xedant Agent data — chats, messages, settings, analytics, and more. The default is **SQLite**, which keeps everything in a single file with no external database server required. Three files may appear: - `project.db` — The main database file - `project.db-wal` — the change journal: WAL mode speeds things up when reading and writing happen at the same time - `project.db-shm` — a shared-memory helper file for WAL mode The database is created on the first run, and its structure updates automatically when the program is updated — you never manage it by hand. You can use PostgreSQL instead of SQLite: set the `AGENT_DATABASE` environment variable to a connection string, and the database will be created there. ## telegram.db The database for the [Telegram bot](/agents/agent/docs/telegram) : it stores the mappings between Telegram chats and Xedant Agent chats, plus user settings (active chat, selected skill). It is created automatically when the bot is enabled; its data is not carried over into the main project database. Three files may appear: - `telegram.db` — The main database file - `telegram.db-wal` — the change journal - `telegram.db-shm` — a shared-memory helper file for WAL mode ## proxy.db An SQLite database for the [built-in proxy server](/agents/agent/docs/proxy) — it stores the request log (headers, message texts, tokens spent, duration, errors) and the model’s reasoning cache. It is created automatically when the proxy is activated. Three files may appear: - `proxy.db` — The main database file - `proxy.db-wal` — the change journal - `proxy.db-shm` — a shared-memory helper file for WAL mode Automatic cleanup: 30 days for request logs, 7 days for the reasoning cache. API keys and secrets are filtered out of the stored data automatically. ## Directories ### build/ Stores build output logs. Created automatically when builds run. Each build task produces three files: `{name}.output.txt` (full command output), `{name}.errors.txt` (parsed errors), and `{name}.warnings.txt` (parsed warnings). You can view them in the build panel without opening the files directly. ### deploy/ Stores deployment runtime output and client debug logs. Created automatically when deployments run. Each deployment produces `{name}.log` with the application’s runtime output. Client debug logs are stored as `{domain}.log` (auto-truncated to 100 MB). ### sounds/ An optional directory for **custom notification sounds**. Place `.mp3` files here to override the built-in sounds or add new ones. The built-in sound names are `message`, `notification`, `complete`, `error`, `commit`, and `deploy`. The server checks `.xedant/sounds/` first, then falls back to the built-in defaults. To restore a built-in sound, simply delete your custom file. The `startSound` and `endSound` properties in `build.yml` and `deploy.yml` can reference any built-in sound name or a custom sound placed in this directory. ### tools/ An optional directory for **utility scripts**. Put any helper scripts you want to use with your project here — diagnostic tools, deployment helpers, or custom automation. This directory is not created automatically. ## Auto-created Files The following files are created automatically on the first run if they do not exist. You can safely delete any of them — they will be restored from the built-in defaults the next time Xedant Agent starts: - `project.yml` — Project metadata (the name is auto-detected from git remote) - `.gitignore` — Default ignore patterns for the `.xedant/` directory - `output.parser` — Parser rules for generic script output - `build.parser` — Parser rules for build output - `deploy.parser` — Parser rules for deployment output - `telegram.yml` — Telegram bot configuration - `providers.yml` — AI provider definitions and templates - `README.md` — Format documentation for all configuration files (read by the AI model) Configuration files (`build.yml`, `deploy.yml`, `project.yml`, `hooks.yml`, `mcp.yml`, `skills.yml`, `models.yml`, `providers.yml`, `telegram.yml`, `tasks.yml`, `bots.yml`, `miniagent.yml`) and the `*.parser` rule files are also automatically **validated** when saved. Validation results appear in the build panel next to the regular builds — errors in red, warnings in yellow — with links to the matching section in `README.md`, so you can look up the correct format. **[← Licensing](/agents/agent/docs/licensing)** **[Remote Control →](/agents/agent/docs/remote-control)**