Project storage and networking
User data
By default, the application separates shared configuration from runtime state:
~/.agent-compositor/
agent-compositor.json # global application settings
mcp.json, proxy.json, ... # global component settings
plugins/ # user extensions
marketplaces.json # user marketplace registrations
credentials.json # private credentials
approvals/ # saved project approvals
plugin-state/<plugin>/ # plugin memory with scope=global
projects/<directory>-<hash>/
project.json # canonical cwd and migration version
sessions/ # session JSONL and metadata
agents.json, worktrees/ # independent agents
todos.json # tasks
workflows/ # code and replay journals
turn-checkpoints/ # code/conversation snapshots
layout.json, model.json # local preferences
memory.md # private memory for this project
plugin-state/<plugin>/ # JSON state with scope=project
session-state/<id>/<plugin>/
cache/<plugin>/ # rebuildable indexes
<project>/.agent-compositor/
agent-compositor.json # project settings
mcp.json, proxy.json, ... # shared project overrides
plugins/, skills/ # project extensions/instructions
marketplaces.json # project marketplace registrations
The identifier includes the canonical path and its hash, so directories with the
same name do not share sessions. Git worktrees have separate cwd/state.
Independent agents inherit application profiles and component settings from their
parent; local settings take precedence while runtime task/memory state remains
separate. Moving a checkout to a different path creates a new project identity.
AGENT_HOME selects an alternative user root; AGENT_STORAGE_MODE=project
explicitly enables the previous portable mode. XDG global configuration is also
supported. Application configuration precedence is user root → XDG → project
walk; component settings use global → project → private local preferences.
JSON objects are merged; arrays are replaced.
On first startup, runtime files from the old <cwd>/.agent-compositor directory
are copied into the new store without deleting the originals. A marker prevents
reimporting stale state. Migration covers sessions, agents, Todos, layout/model,
checkpoints, workflows, and legacy extension metadata. COMPOSITOR.md is copied to
private memory.md. Old directories remain available for inspection or backup.
Skills support global and project directories. # note saves private project
memory and #global note saves global memory owned by the memory plugin. Both
commands preserve the existing shared COMPOSITOR.md file in the project.
Project instructions
At startup, the standard loader looks for AGENTS.md, CLAUDE.md and
GEMINI.md in the user root, the project root and the project's
.agent-compositor directory. A path reference
can also load instructions scoped to the selected paths.
Each load must fit in 120,000 UTF-8 bytes, including the generated file headings and separators. All startup instructions share one limit. Scoped instructions for all references in a submission share another. Instructions are included in full. If the total exceeds the limit or an applicable instruction file cannot be read as valid UTF-8 text, startup or reference preparation fails with an error. Fix the indicated file or shorten the combined instructions and retry. These bytes are accounted separately from the submitted text and reference previews.
Reasoning effort
Explicit provider profile references resolve only profiles actually configured on the router; inherited object properties are not provider profiles. An unknown profile is rejected before a model request or a reasoning-setting change.
Open Settings → Models & providers (or /model) and choose Reasoning under
the desired profile. It is also available in Edit connection. Save for this
project or all projects; project settings override global defaults. The active
profile's effort appears above the list and applies to subsequent requests,
including after restart. Changing effort preserves a manually selected model ID.
Provider default clears the explicit value, including an inherited legacy
value; it does not mean that the model disables reasoning.
Profiles store the optional reasoningEffort in providers.json, separately
from credentials. The UI offers protocol choices, not a guarantee that a selected
model accepts every choice. Unsupported values can be rejected by the provider;
choose its supported level or Provider default. Existing custom gateway values
remain visible when editing.
The transports send OpenAI-compatible reasoning_effort, Responses
reasoning.effort, Anthropic output_config.effort, or Gemini
thinkingConfig.thinkingLevel (uppercase enum). The available values and model
restrictions come from the provider: OpenAI reasoning,
Anthropic effort,
and Gemini ThinkingLevel.
Plugin API
const config = await $.storage.config('my-plugin.json');
await $.storage.set('progress', { completed: 3 }, 'project');
const progress = await $.storage.get('progress', 'project');
await $.storage.set('preferences', { compact: true }, 'global');
await $.storage.set('cursor', { row: 4 }, 'session');
await $.storage.set('symbols', { items: [] }, 'cache');
JSON values are written atomically, bounded by the host write budget, and
namespaced by plugin. get returns undefined for missing keys. Operations pass
through service.storage.config/read/write and can be intercepted by hooks.
Writes during ui.render are forbidden. Traversal and symlink escapes are
rejected. $.storage.paths exposes home/state/project. $.state remains temporary
in-memory state; use storage to persist values across sessions.
Legacy $.fs.read/write('.agent-compositor/...') redirects runtime writes to
private state, with reads falling back to old/project/global files for
compatibility. Arbitrary Node fs calls are not rewritten automatically:
ToolContext provides stateDir, settings(name), and fetch for native plugins
to use explicitly.
Keeping Callix current
Callix saves its JSON graph and fingerprint in cache/callix/index.json.
The fingerprint is checked before reading the graph; a valid cache is reused after
restart. An active session debounces background refreshes after external source
edits, Git HEAD/index/refs changes in the working tree, and project.changed
events after write/edit. .git, state, node_modules, and build/dist directories
are excluded from source indexing. Systems without recursive watch still have
tool hooks and fingerprint checks on query. Indexing does not run as a continuous
polling loop.
{ "background": true, "debounceMs": 750 }
These are callix.json settings. background: false leaves only refresh on query.
Processes, timers, and watchers are released on unload/close; background indexing
errors go to telemetry. During continuous edits, the index may lag until a
rebuild finishes; queries check the fingerprint rather than assuming an old graph
is current.
Proxy routing
The replaceable default network-proxy plugin reads proxy.json and configures
the shared client through service.network.configure. Routing defaults to off.
Configuration is validated before model requests and network tools; an invalid
enabled proxy must not silently fall back to a direct connection.
{
"enabled": false,
"url": "http://127.0.0.1:7890",
"noProxy": ["localhost", "127.0.0.1", "::1"],
"models": true,
"tools": true
}
Set your endpoint, then use /proxy on; /proxy status and /proxy off display
and change the mode. Status hides the password in the URL. Local preferences are
stored in private state; the example endpoint is not enabled automatically.
Node uses Undici ProxyAgent/CONNECT; Bun uses its native fetch proxy support. Native OpenAI/Anthropic/Gemini/OpenAI-compatible protocols and streaming are preserved. Provider OAuth/refresh/quota and web tools use the same route. Shell/MCP receive HTTP_PROXY/HTTPS_PROXY/ALL_PROXY/NO_PROXY for clients that support those variables. Global process.env is unchanged. An explicit MCP server/command env can override them. Arbitrary HTTP code in third-party plugins is not intercepted automatically: use ToolContext.fetch or the client's own settings. Socks and OpenAI-to-Anthropic protocol translation are outside this implementation.
Ollama remains available at http://127.0.0.1:11434/v1. This environment was tested
with gemma4:31b-cloud and deepseek-v4.1-flash:1017-cloud: the local Ollama
serves the API while inference runs in the cloud. OpenAI/Anthropic can be
configured later through the existing provider profiles and credentials using
the same transport.
Native provider and proxy settings
Click Settings in the workspace bar, or run /settings, /providers or
/models. Add provider offers Ollama, OpenAI Responses, Anthropic, Gemini
and an OpenAI-compatible gateway. Enter a profile ID, base URL, model ID and
optional API key. Test & discover models calls the provider's model-list
endpoint without issuing a completion; choose a returned ID or enter one
manually when a gateway does not expose that endpoint. Existing profiles offer
edit, test, model selection and removal. Changing the ID in the editor creates
a copy. Removing a profile hides it for this project and retains its credentials.
Forms support mouse focus, Tab/Shift+Tab and arrow navigation, editable text,
masked passwords, toggles and selectable options. Ctrl+A replaces a whole field;
Ctrl+U clears it. Enter advances text fields or activates a selected button.
Escape cancels without saving. Connection testing does not save a draft.
/login <profile> opens a masked API-key form unless the profile already has a
configured OAuth device flow. The existing environment-variable login remains
available. Blank key/password fields retain existing credentials; use the
explicit removal switch to clear a stored value.
Network proxy opens the proxy form directly; /proxy and /proxy configure
do the same. Configure an HTTP(S) CONNECT endpoint, optional username/password,
separate model/tool switches and bypass hosts. SOCKS is not supported. Model
list requests use the same network client and proxy policy as completions.
/proxy status, /proxy on and /proxy off remain available.
Choose project or global scope when saving. Project connections and proxy
settings are stored in the private project state directory; global defaults use
~/.agent-compositor/providers.json and proxy.json. Project overrides take
precedence over global defaults. API keys use the private credentials.json
file. Authenticated proxy URLs are private settings, never shared repository
files. Writes are atomic with mode 0600. Model selection is restored from the
private model.json. Form drafts and API keys do not enter prompts, chat history or render hooks.
Form results bypass catalog events; proxy configuration is still consumed by
the existing storage/network service hooks. Displayed proxy status redacts URL
credentials. Visual bench inputs use fake credentials: its input.jsonl is a
raw keystroke diagnostic and must never be used with real secrets.
Trusted plugins can request the same native form with $.ui.form(request).
The request contains a title, optional description, text/password/url/select/
toggle fields and actions. It returns {action, values} or null on cancel,
including when a selected form controller returns its cancel action.
Cancellation does not require completed fields and discards their values.
Password fields cannot declare a nonempty initial value. The host owns the
modal, masking, scrolling and draft lifecycle. Set an appropriate manifest
hookTimeouts budget (the built-in editors use 300000 ms) when awaiting input. Headless hosts reject forms
unless an application explicitly installs a form handler. Form results travel
through a private host callback rather than service.* events. Similarly,
$.storage.configure(name, value, 'project' | 'global') writes private component
settings through a trusted host callback. These two APIs are unavailable to
sandboxed/render-only plugins and cannot run inside ui.render.