Project Settings (.agentix/ directory)

The .agentix/ directory in your project root lets you configure agent behaviour, define sub-agents, slash commands, and rules without modifying code.

Directory structure

<cwd>/                             ← project root (workspace)
├── AGENTIX.md                     ← appended to the agent's system prompt
├── AGENTIX.local.md               ← local-only guidelines (gitignore this!)
└── .mcp.json                      ← MCP server configs bundled with this project/plugin

<cwd>/.agentix/                    ← agentix project directory
├── settings.json                  ← project-level config overrides
├── settings.local.json            ← machine-local overrides (gitignore this!)
├── AGENTIX.md                     ← also loaded here and merged with repo-root AGENTIX.md
├── gateway.yaml                   ← gateway config (standalone deployments only)
├── .env                           ← env-var overrides for gateway
├── agents/
│   └── researcher.md              ← sub-agent definition
├── commands/
│   └── deploy.md                  ← slash command definition
├── rules/
│   └── safety.md                  ← additional system prompt rule fragments
├── output-styles/
│   └── concise.md                 ← named output style document
└── skills/
    └── <skill-name>/              ← project-level custom skills

Runtime directories created automatically when memory is enabled:

<cwd>/.agentix/
├── memories/                      ← main agent persistent memory
├── agent-memory/
│   └── <agent-slug>/             ← sub-agent "project" scope memory
└── agent-memory-local/
    └── <agent-slug>/             ← sub-agent "local" scope memory

---

AGENTIX.md

Agentix looks for AGENTIX.md in two locations and merges both if present:

1. <cwd>/AGENTIX.md — project root (repo-level, checked in to version control)
2. <cwd>/.agentix/AGENTIX.md — inside the agentix dir (also checked in)

Additionally, ~/.agentix/AGENTIX.md is loaded as a user-level guideline, and AGENTIX.local.md at the project root is loaded as a machine-local supplement (gitignore this).

The combined content is appended to the agent's system prompt on every run. Use it for project-specific context:

# Project Context

This is a Python 3.12 web application using FastAPI and PostgreSQL.
- Database migrations are in `alembic/versions/`
- Tests use pytest; run with `pytest -x`
- Never commit directly to `main`

---

settings.json

Project-level JSON configuration. Keys mirror AgentixAgentOptions fields and are merged over user-level defaults.

{
  "max_iterations": 30,
  "allowed_tools": ["Read", "Glob", "Grep", "Bash"],
  "max_conversation_window": 15
}

Permissions

Tool allow/deny rules can be set directly in settings.json under a "permissions" key instead of (or as a fallback for) AgentixAgentOptions.allowed_tools / disallowed_tools:

{
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash", "Write"]
  }
}

Hooks

Hooks are also registered via settings.json under a "hooks" key. Each entry maps an event name to a list of hook matcher configs:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": ["myproject.hooks:audit_bash"]
      }
    ]
  }
}

---

settings.local.json

Machine-local overrides — highest precedence after inline AgentixAgentOptions fields. Gitignore this file:

{
  "provider": "openai",
  "model": "gpt-4o"
}

---

Settings merge order

Settings are applied in this order — later sources win over earlier ones:

Priority	Source	File
1 (lowest)	"user"	~/.agentix/settings.json
2	"project"	<cwd>/.agentix/settings.json
3	"local"	<cwd>/.agentix/settings.local.json
4	inline settings dict	AgentixAgentOptions(settings={...})
5 (highest)	explicit fields	AgentixAgentOptions(model="...", ...)

By default all three file sources are loaded. Explicit AgentixAgentOptions fields always win regardless of what any settings file contains.

setting_sources

Use setting_sources to control exactly which file layers are loaded. The three recognised values are "user", "project", and "local":

Value	File	Purpose
"user"	~/.agentix/settings.json	Personal defaults shared across all your projects
"project"	<cwd>/.agentix/settings.json	Checked into version control, shared with the team
"local"	<cwd>/.agentix/settings.local.json	Machine-specific overrides, gitignored

# Default — all three sources loaded (setting_sources omitted)
options = AgentixAgentOptions(name="my-agent")

# CI/CD — only the committed project settings, no personal or local overrides
options = AgentixAgentOptions(
    setting_sources=["project"],
)

# Development — project + local machine overrides, skip user-level defaults
options = AgentixAgentOptions(
    setting_sources=["project", "local"],
)

# Fully self-contained — ignore all settings files entirely
options = AgentixAgentOptions(
    setting_sources=[],
)

setting_sources=[] disables all file-based settings. Only inline AgentixAgentOptions fields and the settings dict apply — useful for tests or hermetic deployments where you want zero filesystem reads.

---

agents/*.md

Sub-agent definitions loaded from Markdown files. The frontmatter provides the spec; the body becomes the agent's prompt:

---
name: researcher
description: Searches the web and summarises findings.
tools:
  - WebSearch
  - WebFetch
---

You are a research specialist. Always cite your sources.

See Multi-agent for all supported frontmatter fields.

---

commands/*.md

Slash command definitions for interactive sessions:

---
name: review
description: Review the current git diff.
---

Review the output of `git diff HEAD` and provide a concise summary of changes.

---

rules/*.md

Additional rule fragments appended to the system prompt, loaded in lexicographic filename order. Use these to separate concerns — for example, a safety policy in one file and coding standards in another:

.agentix/rules/
├── 01-safety.md
└── 02-coding-standards.md

---

output-styles/*.md

Named output style documents. Select one at runtime via the outputStyle setting or AgentixAgentOptions.settings:

{
  "outputStyle": "concise"
}

<!-- .agentix/output-styles/concise.md -->
Respond in plain language. Be direct and brief. No bullet points unless asked.

---

.mcp.json

Place .mcp.json at the project root (not inside .agentix/) to declare MCP servers that are bundled with the project or plugin. When Agentix loads the project as a plugin, these servers are discovered automatically and merged into mcp_servers alongside any servers defined inline in AgentixAgentOptions.

The file uses a single top-level "mcpServers" key:

{
  "mcpServers": {
    "my-http-server": {
      "type": "http",
      "url": "https://my-mcp-server.example.com/mcp"
    },
    "my-stdio-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": { "MY_VAR": "value" }
    },
    "my-sse-server": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "headers": { "Authorization": "Bearer ${MY_TOKEN}" }
    },
    "my-jsonrpc-server": {
      "type": "jsonrpc",
      "url": "http://localhost:8080/mcp",
      "timeout": 30.0
    }
  }
}

Each entry supports the same config shapes as mcp_servers in AgentixAgentOptions — see MCP Servers for the full field reference per transport type.

If a server name in .mcp.json clashes with one already defined inline in AgentixAgentOptions.mcp_servers, the inline definition takes precedence (it is registered first, before plugin loading runs).

---

Gateway configuration

Place gateway.yaml in .agentix/ for standalone gateway deployments. Optionally add a .env file alongside it for environment variable overrides:

<cwd>/.agentix/
├── gateway.yaml
└── .env

See Gateway and YAML Configuration for full details.