Project Settings (.agentix/ directory)

The .agentix/ directory in your project root lets you configure agent behavior, define commands, and add hooks without modifying code.

Directory structure

<cwd>/.agentix/
├── AGENTIX.md              ← appended to the agent's system prompt
├── settings.json           ← project-level overrides
├── settings.local.json     ← machine-local overrides (gitignore this!)
├── agents/
│   └── researcher.md       ← sub-agent definition
├── commands/
│   └── deploy.md           ← slash command definition
├── hooks/
│   └── audit.py            ← each file must define register(hooks_dict)
└── permissions.json        ← permission rules

AGENTIX.md

Content is automatically appended to the agent's system prompt. 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:

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

settings.local.json

Machine-local overrides (gitignore this file). Useful for developer-specific settings:

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

Settings merge order

1. ~/.agentix/settings.json (user-level)
2. <cwd>/.agentix/settings.json (project-level)
3. <cwd>/.agentix/settings.local.json (local-level)
4. AgentixAgentOptions.settings dict (inline)
5. Explicit AgentixAgentOptions fields (highest priority)

Control which layers are loaded with setting_sources:

options = AgentixAgentOptions(
    setting_sources=["project", "local"],  # skip user-level settings
)

Hook files

Each .py file in hooks/ must define a register(hooks_dict) function:

# .agentix/hooks/audit.py
import logging

def register(hooks: dict) -> None:
    hooks.setdefault("PreToolUse", []).append(
        # HookMatcher instance
        ...
    )

agents/*.md

Sub-agent definitions loaded from Markdown files:

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

You are a research specialist. Always cite your sources.

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.

Gateway configuration

Place gateway.yaml in .agentix/ for standalone gateway deployments:

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

See Gateway for full gateway documentation.