Configuration

Environment variables and on-disk paths agentty reads.

agentty is configured through flags, environment variables, and two on-disk paths. There is no sprawling config file to learn.

Environment variables

The most commonly used ones are below. For the complete list — every variable agentty reads, grouped by subsystem — see Environment variables.

Variable	Effect
`ANTHROPIC_API_KEY`	Claude API key used when no -k flag is passed. Second-highest priority in credential resolution.
`CLAUDE_CODE_OAUTH_TOKEN`	OAuth token from the env (reuses Claude Code's token) — below API key but above on-disk creds. No refresh token.
`OPENAI_API_KEY`	Key for --provider openai, and the fallback key for every other OpenAI-compatible provider.
`GROQ_API_KEY / OPENROUTER_API_KEY / TOGETHER_API_KEY / CEREBRAS_API_KEY / DEEPSEEK_API_KEY / GEMINI_API_KEY / XAI_API_KEY / MISTRAL_API_KEY / FIREWORKS_API_KEY`	Provider-specific keys, checked before `OPENAI_API_KEY` for that provider. Gemini also accepts `GOOGLE_API_KEY`. Kimi/ChatGPT/Copilot use `agentty login` (OAuth), not a key. Ollama needs none.
`AGENTTY_SOCKS_PROXY`	Route all TCP through this SOCKS5 proxy host:port (set automatically by airgap mode).
`AGENTTY_API_HOST`	Override the API host (host[:port]) — dial a different upstream, keeping normal TLS chain verification (and any `AGENTTY_TLS_PINS` you set).
`AGENTTY_OAUTH_HOST`	Override the OAuth host (host[:port]).
`AGENTTY_INSECURE`	Set to 1 to skip TLS peer verification. Last-resort only — never ship it.
`AGENTTY_TLS_PINS`	Opt-in public-key pinning: comma-separated base64 SHA-256 SPKI hashes; the handshake fails closed if the leaf cert's key matches none. Off by default. Include a backup pin so cert rotation can't lock you out.
`AGENTTY_USE_KEYSTORE`	Set to 1 to store credentials in the OS secret store (Linux libsecret / macOS Keychain / Windows Credential Manager) in addition to the file. Falls back to the file when no backend is present.
`AGENTTY_ENCRYPT_PASSPHRASE`	Set to 1 to encrypt the credentials file at rest with a passphrase (prompted on the tty, echo off). Sealed with AES-256-GCM under an Argon2id (or scrypt) key.
`AGENTTY_PASSPHRASE`	Supply the at-rest encryption passphrase non-interactively (CI/scripts) instead of the tty prompt.
`AGENTTY_KDF`	Set to `scrypt` to force the portable scrypt KDF instead of the default Argon2id for at-rest encryption.
`AGENTTY_AIRGAP_SSH`	Extra flags injected into the ssh invocation for airgap (laptop side).
`AGENTTY_CLIPBOARD_CMD`	Shell command that writes image bytes to stdout — used for Ctrl+V image paste over SSH. See Clipboard & Images.
`AGENTTY_MCP_CONFIG`	Explicit path to an mcp.json, overriding the project/user lookup.
`AGENTTY_MCP_ALLOW_PROJECT`	Blanket-trust a project-local .agentty/mcp.json so its stdio servers connect (gated off by default). Alternative to per-file content-hash approval.
`AGENTTY_DOCS_DIR`	Folder of documents to index for the search_docs retrieval tool. Auto-discovers `./docs` then `./.agentty/knowledge` when unset. Even with no docs, `search_docs` still searches your installed skills and learned memory.
`AGENTTY_EMBED_MODEL / AGENTTY_OLLAMA_HOST`	Embedding model (default `nomic-embed-text`) + Ollama host (`host:port`, default `127.0.0.1:11434`) for the dense half of the hybrid RAG pipeline. No Ollama → dense falls back to a local hash embedder and hybrid still runs.
`AGENTTY_RAG_SKILLS / AGENTTY_RAG_MEMORY`	Fold installed skills / learned memory into the search_docs corpus. On by default; set `=0` to disable.
`AGENTTY_RAG_MCP`	Fold connected MCP `resources/` into the search_docs corpus. Off unless truthy and* an MCP config is present.
`AGENTTY_RAG_DENSE_WEIGHT / AGENTTY_RAG_BM25_WEIGHT`	Fusion weights for the dense (embedding) vs lexical (BM25) lists. Default `1.0` each. Fusion is convex (TM2C2) — it preserves score magnitude and, per rag-cpp's benchmarks, beats RRF on NDCG.
`AGENTTY_RAG_CONTEXTUAL`	Anthropic Contextual Retrieval: situate each chunk in its document before indexing so a fragment that lost its heading still ranks. On by default (deterministic extractive fallback — no model, index-time cost only); `=0` disables.
`AGENTTY_RAG_PRF`	Pseudo-relevance-feedback (RM3-lite) query expansion: harvest the most discriminative terms from the top BM25 hits and fuse a second, down-weighted probe. On by default (deterministic, sub-ms); `=0` disables.
`AGENTTY_RAG_MMR / AGENTTY_RAG_MMR_LAMBDA`	MMR diversification: drop near-duplicate passages so the model sees distinct information. On by default; `_LAMBDA` trades relevance vs diversity (default `0.5`); `AGENTTY_RAG_MMR=0` disables.
`AGENTTY_RAG_STITCH`	Parent-document stitch: after ranking, fold each surviving chunk back into its adjacent siblings so the model reads the hit in context. On by default (in-memory, no network); `=0` disables.
`AGENTTY_RAG_GRAPH`	GraphRAG local multi-hop expansion: seed with hybrid, walk the document graph (links + shared-entity edges) and fuse in supporting passages a flat index misses. On by default (deterministic, in-memory); `=0` disables.
`AGENTTY_RAG_CORRECT`	CRAG corrective grading: a model-free retrieval evaluator drops passages graded irrelevant and yields a calibrated confidence in `[0,1]` — the signal the proactive-injection gate reads. On by default; `=0` disables.
`AGENTTY_RAG_OUTPUT_BYTES`	Aggregate body budget across all returned passages (default `12288` ≈ 3k tokens). Clamped 2 KiB – 64 KiB.
`AGENTTY_RAG_RELEVANCE_FLOOR`	Token frugality: drop tail passages scoring below `frac × top` before spending any tokens on them — the model ignores the low-confidence tail anyway. The best hit is always kept. Default `0.30`; `0` keeps every hit.
`AGENTTY_RAG_BUDGET_GAMMA`	Token frugality: water-filling budget split — allocate bytes ∝ `score^gamma` (with a per-passage floor) instead of an even total/n split, so confident passages get room to be complete and marginal ones get a tight excerpt. Default `1.5`; higher concentrates budget on the head.
`AGENTTY_RAG_CONF_BUDGET_FLOOR`	Token frugality: scale the total budget by CRAG confidence — a barely-passing retrieval injects a cheap block, a slam-dunk gets full room. Linear ramp from this floor fraction at low confidence to 100% at full confidence. Default `0.45`.
`AGENTTY_RAG_EXTRACTIVE`	Token frugality: model-free LLMLingua-style extractive compression for prose — keep the highest query-overlap sentences within budget and drop the filler between them (code/config keep a contiguous line-window). On by default; `=0` forces the line-window path.
`AGENTTY_RAG_PROACTIVE_BYTES`	Token frugality: independent, tighter cap on the unprompted proactive `<retrieved-context>` block (spent without the user asking). Default `6144` ≈ 1.5k tokens; clamped 1 KiB – 32 KiB.
`AGENTTY_RAG_MEASURE`	Set `=1` so `agentty rag-bench` also runs its queries through the real retrieval output path and reports bytes/estimated-tokens per query plus a machine-readable `MEASURE` line — diff two runs with a lever toggled to quantify its saving. Measurement only; off by default.
`AGENTTY_RAG_EXPAND / AGENTTY_RAG_HYDE / AGENTTY_RAG_GEN_MODEL`	LLM-assisted recall: multi-query / RAG-Fusion (`_EXPAND`) and HyDE (`_HYDE`), both opt-in (`=1`), powered by a small local Ollama model (`_GEN_MODEL`, default `qwen2.5:0.5b`) on the same Ollama used for embeddings. If Ollama is unreachable they silently no-op and plain hybrid still runs; they are also skipped on the latency-sensitive proactive pre-turn path.
`AGENTTY_RAG_PERSIST`	Cache the built docs index to `.agentty/rag_docs.ragdb` so a later session opens warm without re-walking + re-embedding. On by default; `=0` disables.
`AGENTTY_RAG_LEARN`	The learning loop: fold each passage's Beta-smoothed win-rate (`.agentty/rag_feedback.tsv`) back into ranking as a bounded (±15%) nudge, so passages that repeatedly prove useful in this workspace edge ahead of near-tied ones. A `read` of a path retrieval just surfaced counts as a win; unseen paths are untouched (neutral). On by default; `=0` disables (delete the TSV to forget).
`AGENTTY_RAG_TRACE`	Fold rag-cpp's per-stage trace into the retrieval `mode` string for debugging. Off by default; truthy enables.
`AGENTTY_RAG_PROACTIVE / AGENTTY_RAG_PROACTIVE_MIN`	Pre-turn auto-retrieval that injects a `<retrieved-context>` block when a query looks knowledge-shaped. Off by default (explicit opt-in — the `search_docs` tool is usually more economical); `=1` enables for the session, or turn it on persistently via Ctrl+K → RAG. `_MIN` is the CRAG-calibrated confidence bar to inject (default `0.35`).
`AGENTTY_RAG_PROACTIVE_BUDGET_MS`	Fast-path hedge for the proactive pre-turn retrieval. The submit thread waits at most this long for the funnel; if it lands, grounding is injected inline with zero added latency. If it overruns the submit thread never blocks — the turn enters its normal streaming state (status shows retrieving context…, the UI never feels hung) and the stream launch is HELD behind a background retrieval that injects the block same-turn the moment it lands. Grounding is always for the question just asked; it is never dropped or deferred to a later turn. Default `250`; `0` skips the inline hedge.
`BM25_USE_STEMMER / BM25_HEADING_BOOST`	Lexical tuning. Porter stemming ("run/runs/running" match) is on by default; set `BM25_USE_STEMMER=0` to disable (e.g. a code-symbol corpus). `BM25_HEADING_BOOST` (default 3) is how many times a chunk's heading breadcrumb is folded into its BM25 tokens — heading matches out-score body matches; 1 disables the boost.
`AGENTTY_LOG`	The diagnostic knob — one log, every subsystem. RUST_LOG-style filter: `trace`, `debug`, `wire=trace`, `warn,auth=debug`, `off`. Channels: `wire` (raw request/response bytes, untruncated, tagged by dialect), `auth`, `persist`, `tool`, `ui`, `rag`, `mcp`, `acp`, `smart`, `net`, `general`. Release builds keep warnings + errors by default (~2 lines per healthy session), so `agentty diagnostics` produces a useful bug report with no setup; non-release builds capture everything. When a model "ignores tools", sends empty tool arguments, or a turn fails in a way that looks like model quality, `AGENTTY_LOG=wire=trace` shows the actual bytes instead of leaving you to guess. The file holds your conversation (prompts, file contents, tool results); request headers are not logged, so API keys stay out of it. See Logging & diagnostics.
`AGENTTY_LOG_BODIES`	Include payloads (wire bodies, tool args) in the log. Off by default; these carry user data. The log destination is the `--log-file` flag, not a variable.
`AGENTTY_SMART_MODE`	Session pin for the Smart Mode master switch: `1` forces on, `0` forces off, for that process only. Never persisted (safe for CI / benchmarks). Unset = your saved setting governs.
`AGENTTY_SMART_NO_INTERNAL`	Escape hatch: keep engine-internal calls (compaction summary, thread title) on the main model instead of the Utility slot. For bisecting a routing bug — Smart Mode's three behaviours are otherwise one switch.
`AGENTTY_SMART_NO_ORCHESTRATE`	Escape hatch: run the main turn on the selected model instead of the Strategic slot, and drop the delegation directive.
`AGENTTY_SMART_NO_SUBAGENTS`	Escape hatch: resolve each `task` worker's model with the tier auto-router instead of by its role.
`AGENTTY_NO_TRANSFORMS`	Set to 1 to drop the transform/aggregate/structured-data tool family (`extract`, `aggregate`, `replace`, `read_filter`, `json_query`) — trims ~5 KB of tool schema off every request for a minimal or latency-sensitive profile, without losing `grep`/`read`/`edit`. On (family present) by default.
`AGENTTY_TRACE_TOOLS`	Older spelling of `agentty run --events jsonl`; `=1` selects the same stream. Prefer the flag — it appears in `--help`. Emits JSON lines to stderr (turns, reasoning, answer text and one per tool call), so the stdout answer stays clean and a harness can capture both. See agentty run.
`SSL_CERT_FILE / SSL_CERT_DIR / CURL_CA_BUNDLE`	Override the TLS root store agentty trusts (standard OpenSSL vars).

Smart Mode tuning

The Smart Mode feature toggles (which layers run) live in the Ctrl+S overlay and persist to settings.json. These are the numeric policy knobs below that — advanced tuning, read at point of use and clamped to a safe range (unset ⇒ the shipped default). Only genuine policy is exposed; the signature hash space, storage compaction thresholds, and individual classifier feature weights are deliberately fixed (changing them corrupts stored learning or breaks invariants).

Variable	Meaning
`AGENTTY_SMART_COMPLEX_THRESHOLD`	Feature-score at/above which a turn classifies as Complex (more reasoning, more cost). Lower ⇒ more turns escalate; higher ⇒ fewer. The Simple/Standard boundary tracks it. Default `3`; range 1–8.
`AGENTTY_SMART_DEEP_MARGIN`	How far into a tier (score margin) a turn must sit to earn the extra continuous effort step — a genuinely hard Complex turn reaches +2 immediately instead of waiting for the session bias to drift. Lower ⇒ eager; higher ⇒ stays close to the discrete tier. Default `3`; range 1–8.
`AGENTTY_SMART_BIAS_CLAMP`	Symmetric cap (±N steps) on the session cascade bias — how far this session's self-correction can drift effort from baseline. Default `2`; range 1–4.

Web search

Ctrl+K → Settings → Web Search edits these and saves them to settings.json under "web_search". A variable wins over a saved value for that session only: it locks the matching row in the pane (naming the variable) and is never written to settings.json, so unsetting it restores what you saved.

Variable	Meaning
`AGENTTY_WEB_SEARCH`	`auto` (default), `on`, or `off`. `auto` advertises `web_search` and leaves the result count to the model, as agentty did before the Web Search pane. `on` applies your `AGENTTY_WEB_SEARCH_COUNT` and `_MAX`. `off` removes `web_search` from every request, from the tool list `agentty mcp-serve` offers to other MCP clients, and refuses any call to it (a replayed thread, a call injected by an ACP client). `0`/`false`/`no` mean `off`; `1`/`true`/`yes` mean `auto` (search available, the model picks the count).
`AGENTTY_WEB_SEARCH_COUNT`	Results when the model does not say how many. Applies only in `on`. Default `10`; range 1–20.
`AGENTTY_WEB_SEARCH_MAX`	Most results the model may ask for in one search; a larger request is clamped, and `0` or a negative count becomes `1`. Applies only in `on`. Default `20`; range 1–50. A search returns at most one result page from the service that answers, and each service caps it: 20 on Brave, Tavily, Serper and Perplexity, 30 on DuckDuckGo, 100 on Firecrawl and Exa. A larger request is cut to that cap.
`AGENTTY_WEB_SEARCH_EXCLUDE`	Domains never to return, space- or comma-separated (`pinterest.com w3schools.com`). Pasted URLs and `www.` are reduced to the host. Sent as `-site:` operators to Brave, DuckDuckGo, Serper and Perplexity, and as the service's own domain filter to Tavily, Firecrawl and Exa, so an excluded site never comes back and its slot goes to another result.
`AGENTTY_WEB_SEARCH_PRIMARY`, `_SECONDARY`, `_FALLBACK`	Which service answers first, second and last; the first to succeed wins. A service id: `brave-free`, `ddg-free`, `tavily-free`, `firecrawl-free` (no account, card or key) or `brave-api`, `tavily-api`, `firecrawl-api`, `exa-api`, `serper-api`, `perplexity-api` (need an API key). `_SECONDARY` and `_FALLBACK` also take `none`. Defaults: `brave-free`, `ddg-free`, `tavily-free`.
`AGENTTY_WEB_SEARCH_LANGUAGE`	`auto` (default) or a two-letter code (`en`, `de`, `ja`, ...) sent to the services that take one: Tavily, Brave API, Serper, Perplexity. The others ignore it.
`AGENTTY_WEB_SEARCH_KEY_<SERVICE>`	An API key, taken from the environment instead of the key store: `AGENTTY_WEB_SEARCH_KEY_EXA_API`, `_BRAVE_API`, `_TAVILY_API`, `_FIRECRAWL_API`, `_SERPER_API`, `_PERPLEXITY_API`. Wins over a stored key and locks that row in the pane. Never written to disk.

Choosing the services

The Free services need no account, card or key, but they are best effort: Brave Free and DuckDuckGo Free read a public results page, and Tavily Free and Firecrawl Free use the vendors' key-less tiers. Any of them can be blocked, rate-limited or withdrawn without notice. In particular, many networks are served a captcha by DuckDuckGo and Brave answers 429 after a burst of roughly ten searches. The report from a failed search names each service and why it did not answer (blocked, rate limited, quota used up, key refused, unreadable reply) rather than a bare error.

The API key services are the vendors' documented interfaces and do not depend on a page layout. Paste a key into the row under the slot that uses it and press Enter. It is stored encrypted (the OS keystore when AGENTTY_USE_KEYSTORE is set, otherwise a machine-bound sealed file) and is never written to settings.json; the row then reads ✓ key saved and stays locked until Remove key forgets it. A key from AGENTTY_WEB_SEARCH_KEY_<SERVICE> reads ● key from the variable and is locked for as long as it is set. A keyed service chosen with no key is reported as such in the search result and the next slot is tried.

Each service offers up to three extra settings (freshness, region, category, ...) which appear under its slot, and none for a service that has none. They are saved per service in settings.json under web_search.dials, so a choice survives moving the service between slots.

Kagi, Mojeek and Linkup are not offered yet: their request and response formats could not be verified against documentation or a real reply.

On-disk paths

agentty keeps everything in two places: ~/.agentty for you, and <project>/.agentty for each repo. agentty config shows the real paths and sizes on your machine. The full map, with what every file is and how long it stays, is in Storage.

~/.agentty/                       ($AGENTTY_HOME)
  settings.json  mcp.json  hooks.json  skills/  AGENTS.md   hand-edited config
  threads/     conversations, 0700           $AGENTTY_THREADS_DIR
  credentials/ sign-ins and keys, 0700       $AGENTTY_CREDENTIALS_DIR
  state/       approval hashes               $AGENTTY_STATE_DIR
  cache/       refetchable, safe to delete   $AGENTTY_CACHE_DIR
  logs/        rotates at 32 MB              $AGENTTY_LOGS_DIR
  memory.jsonl

<project>/.agentty/               ($AGENTTY_PROJECT_DIR)
  cache/   search indexes, rebuildable       $AGENTTY_RAG_DIR
  state/   search feedback                   $AGENTTY_PROJECT_STATE_DIR
  memory.jsonl  mcp.json  skills/

Every directory moves on its own with its variable. Storage is set by environment only; nothing in the app changes it. Relative paths are relative to the root, never your current folder. Empty means unset. If a folder can't be made you get one warning and the default.

Threads are the only thing that grows without limit. To expire old ones:

export AGENTTY_THREADS_KEEP_DAYS=90

agentty config move threads /mnt/big/threads moves a folder's data and prints the export line to add (refuses while agentty runs, verifies the copy before removing anything). agentty config doctor checks permissions and overrides. agentty config clean lists files older versions left behind, and --yes deletes them.

Credentials are plaintext JSON by default, optionally sealed with AES-256-GCM (AGENTTY_ENCRYPT_PASSPHRASE) or kept in the OS keystore (AGENTTY_USE_KEYSTORE). See Authentication.

A project mcp.json that starts processes only runs after you approve its exact bytes (Plugin Trust). Approvals live in your state/, so a repo can't approve itself.

Memory scope

A remembered fact lives in one of two files: project (<project>/.agentty/memory.jsonl, this codebase only) or user (~/.agentty/memory.jsonl, every workspace). Project is the default — most facts you keep are about the repo in front of you.

agentty routes a fact smartly so a personal preference never bleeds into every repo. When you (or the model) don't pin a scope, it reads the fact text: a fact plainly about you — first-person “I prefer” / “my name is”, personal tooling — is auto-routed to user scope, and the reply notes scope→user (reason). A fact about the codebase — a build command, a source path, “in this project we…” — stays project.

The correction is one-directional and conservative: it only ever nudges project→user (a personal fact escaping into shared project memory is the harm; the reverse is merely narrow), only when the signal is confident, and an explicit scope always wins. It's a deterministic guardrail on the model's judgment, not a second model call.

Both files are plain JSONL you can inspect or hand-edit. Project scope is only offered when the project directory is writable — under --workspace / (no containing project) everything falls back to user scope. The same underlying scope-resolution logic also drives skills, agents, and slash-command discovery (project shadows user, native .agentty shadows the .agents/.claude interop dirs).

CLAUDE.md guidance

On the Claude backend, agentty appends up to three user-authored guidance files to the system prompt (each capped at 64 KiB, mtime-cached):

~/CLAUDE.md — user tier (every workspace).
<project>/CLAUDE.md — project tier.
<project>/CLAUDE.local.md — local tier (gitignore it for personal notes).

AGENTS.md guidance

agentty also reads the AGENTS.md open standard — stewarded by the Agentic AI Foundation under the Linux Foundation — for project-scoped agent guidance. Think of AGENTS.md as a README for agents: a dedicated, predictable place to provide build steps, test commands, and code-style conventions to AI coding agents. Over 60k open-source projects ship one.

agentty resolves AGENTS.md in three tiers (lowest precedence → highest):

Global scope (~/.agentty/AGENTS.md)

Not part of the published spec (which is project-scoped only), but a pragmatic extension that major tools like Codex (~/.codex/AGENTS.md) and OpenCode (~/.config/opencode/AGENTS.md) implement. agentty checks two candidates in priority order — the first non-empty file wins:

~/.agentty/AGENTS.md — agentty-specific global guidance (highest priority).
~/.agents/AGENTS.md — shared global guidance for any agent tool (fallback).

When present, the content is injected as an <agents-md-global> block before the project-level block, so project guidance overrides global. Capped at 64 KiB.

Project root (<project>/AGENTS.md)

Per the published spec, this is the primary file. agentty reads <project>/AGENTS.md (resolved from --workspace, not the raw process cwd). There is no local tier — that concern stays with CLAUDE.md. When present, the content is injected as an <agents-md> block in the system prompt, placed before the CLAUDE.md <memory> block, so standardized public project guidance lands first and personal/team memory layers on top. Capped at 64 KiB and mtime-cached (same pipeline as CLAUDE.md).

Nested monorepo walk (nearest AGENTS.md)

The spec also describes nested files for monorepos: "Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence." agentty implements this as an upward directory walk:

When the agent's cwd (clamped inside the workspace via project_root()) is a subdirectory of workspace_root, agentty walks upward from the cwd toward the workspace root, looking for the closest AGENTS.md that is not the root file.
The walk stops at the first file found (nearest wins) — it does not collect all files along the path. The nearest file's content is injected as an <agents-md-package> block, after the root block, so the model applies package-specific overrides where they conflict with root-level guidance.
The walk never escapes the workspace boundary.
If the nearest AGENTS.md is the same file as the root (same canonical path — e.g. the cwd is at the workspace root), no <agents-md-package> block is emitted (dedup).
Capped at 64 KiB.

The walk starts from the agent's cwd (project_root()), not from the directory of a specific edited file — a TUI agent has a working directory, not a single "file being edited." In the common case (agent working inside a subpackage directory), the cwd and the relevant package directory coincide, so the nearest AGENTS.md is the package's own.

Wire shape

When AGENTS.md files are present, agentty injects them as separate blocks in the system prompt (low → high precedence):

<agents-md-global>    ← ~/.agentty/AGENTS.md or ~/.agents/AGENTS.md (optional)
<agents-md>           ← <workspace_root>/AGENTS.md (project root)
<agents-md-package>   ← nearest nested AGENTS.md (monorepo walk, optional)

All three tiers are elided when their content is missing or empty, so adding AGENTS.md is purely additive — workspaces without one see no change. Each file is capped at 64 KiB.

Coexistence with CLAUDE.md

AGENTS.md is the cross-tool public standard (works with Codex, Cursor, Jules, Aider, opencode, and many others — see the full list), while CLAUDE.md remains agentty's personal/team memory hierarchy. A repo can ship AGENTS.md for cross-agent conventions and individual users can keep CLAUDE.md / CLAUDE.local.md for their own notes; both are injected, AGENTS.md first.

AGENTS.md is not the same as agentty's subagents. Despite the similar name, AGENTS.md is a document — project guidance injected into the system prompt. It is unrelated to agentty's subagents (the delegate personas in .agentty/agents/*.md that the task tool spawns, shown in the command palette's Subagents entry). One is a project rulebook read into the prompt; the other defines who you can delegate to. AGENTS.md also does not apply to subagents — they run on a lean prompt that excludes both AGENTS.md and CLAUDE.md memory.

Persisted settings

--provider, -m/--model, the reasoning effort tier, favourited models, your permission profile, and your compaction depth are written to ~/.agentty/settings.json whenever you change them in-app — so the next launch resumes exactly where you left off. There is nothing to hand-edit; the picker (^P / ^/) and S-Tab manage it. Compaction depth is set from the command palette's Compaction depth entry — see Providers for why you'd raise it on a 1M-context model.

Choosing a workspace

By default the launch directory is the workspace. Override without cd:

agentty --workspace ~/code/other-project
agentty --workspace /          # opt out of the boundary entirely

TLS trust store

agentty picks up the system trust store at startup. Behind a TLS-terminating corporate proxy, install the proxy's CA into the system store (update-ca-certificates / update-ca-trust). See Corporate Proxies.

← PreviousForking a Thread Next →Smart Mode

✎ Edit this page on GitHub