q

q is a workspace-native coding agent with a local Web control surface. It combines Q Studio, a managed multi-provider LLM gateway, delegated subagents, durable workspace history, and a root-scoped tool runtime in one Go binary.

Use it for ordinary repository work, delegate reviewed implementation, inspect the resulting diff, and create a commit from one local Studio process.

Documentation · Source

What q includes

• Workspace tools — anchored reads and edits, complete-file writes, directory operations, asynchronous commands, archive search, and optional read-only LSP queries.
• Integrated delegation — ordinary chat can use workspace tools directly and assign bounded work to profession-based subagents.
• Provider choice — OpenAI-compatible APIs and local servers, OpenRouter, xAI, Anthropic, the Codex App Server, and Sign in with ChatGPT, all exposed through q's managed Gateway.
• Durable sessions — API-independent conversation records, recoverable delegation trees, and searchable history.
• Composer — a session type to develop ideas through conversation with a selected model, saved history, D2 diagrams, and interactive HTML previews. Refine files together through chat or edit their source beside the preview.
• Bounded tool output — large tool results are captured as immutable Loom artifacts instead of being copied through every prompt.
• Repository review — a syntax-highlighted diff browser and a guided Conventional Commit workflow in Studio.
• Extensibility — external MCP servers, portable Agent Skills, ACP agent connections, and a standalone q-mcp server.

Requirements

• Go 1.26.9 or later
• Git on PATH
• At least one configured model provider
• A local Web browser

Node.js is needed only when changing or rebuilding the embedded Q Studio frontend. Installing and running a released q binary does not require Node.js.

Task is optional; the same build and test commands can be run directly with Go.

Install and run

Install the latest q binary directly from the Go module:

go install github.com/snowmerak/q/cmd/q@latest

Install the optional q-mcp companion the same way:

go install github.com/snowmerak/q/cmd/q-mcp@latest

From a source checkout, install both commands together:

go install ./cmd/q ./cmd/q-mcp

Or run Studio without installing it:

go run ./cmd/q studio

With Task:

task install       # install q and q-mcp into the Go binary directory
task run           # run q from source
task build         # build both commands into ./bin
task test          # test q, the ACP SDK fork, and generated bindings
task dist:check    # verify versioned installation in an isolated module proxy
task studio:install # install pinned Studio frontend dependencies
task studio:check   # type-check and verify generated Studio assets

Start the user-level Studio server. Its start directory does not limit which repositories it can open:

q studio

Studio writes JSONL diagnostics to ~/.q/logs/studio/. Diagnostic stdout output is disabled by default. Files rotate at 25 MiB; managed Studio logs share a 1,000,000,000-byte budget and seven-day retention. A request_id connects HTTP requests, background runs, council rounds and seats, tools, and nested subagents. Valid UUIDs supplied in X-Request-ID are preserved; missing or invalid IDs get a new UUID. Bodies, query strings, conversation content, and raw error details are omitted. Configure logging in ~/.q/config.yaml; see Studio logging for settings, retention, and failure behavior. Embedded Studio servers are silent unless a logger is supplied with studio.WithLogger.

The default INFO logs include tool names and call IDs for root sessions, nested subagents, and councils, plus model calls with selected/reported model IDs, streaming mode, status, duration, and reported token usage. Model fallbacks get separate call IDs under the same request ID.

Studio listens on 127.0.0.1 with a random available port by default. Pin the local address when a stable URL is useful:

q studio --host 127.0.0.1 --port 7070

To reach Studio from another device on a trusted network, listen on every IPv4 interface and open http://<this-machine-ip>:7070 yourself:

q studio --host 0.0.0.0 --port 7070 --no-open

--host accepts an IP address such as 127.0.0.1, 0.0.0.0, ::1, or ::. Port 0 selects a random available port. Studio has no built-in HTTP authentication and can run files, processes, and Git operations with the q process's permissions. Bind it to a non-loopback address only on a trusted, firewalled network or behind an authenticated reverse proxy.

Studio opens in the browser. Add a Gateway provider under Settings → Providers, refresh Models, and choose the default model. Provider keys can come from environment variables; server access keys are shown only once when created. Open Sessions, choose a repository, then register an existing root session or create a new one. Registered roots and their delegated sessions appear in one global tree.

The bare q command remains a compatibility terminal client. Former standalone configuration commands such as q model, q gateway, q systemone, q skills, and q help now open their corresponding Studio surface. q studio also starts the standalone Gateway listener using the saved Gateway address and providers. q gateway start, q systemone start, and q library start still run foreground services independently of Studio.

Embed the Agent Loop in Go

External Go applications can call the same Agent Loop used by q's TUI and ACP without starting the Gateway, TUI, session store, Library, or workspace memory. The host owns the client, workspace root, event handling, persistence, and dependency lifetimes:

Import github.com/snowmerak/q/agentloop, github.com/snowmerak/q/client, and github.com/snowmerak/q/tools for this example.

ctx := context.Background()
root := `C:\path\to\workspace`

modelClient, err := client.FromEnvironment("gpt-5")
if err != nil {
	log.Fatal(err)
}
defer modelClient.Close()

toolRuntime, err := tools.NewRuntime(ctx, root)
if err != nil {
	log.Fatal(err)
}
defer toolRuntime.Close()

messages := agentloop.PrepareWorkspaceMessages(nil, agentloop.WorkspaceMessageOptions{
	Root: root,
	Tools: toolRuntime,
})
messages = append(messages, client.Message{
	Role: client.RoleUser, Content: "Inspect this workspace and explain its entry points.",
})

events := make(chan agentloop.Event)
go agentloop.RunAgentLoop(ctx, agentloop.Request{
	Client: modelClient,
	Tools: toolRuntime,
	Model: "gpt-5",
	Messages: messages,
	WorkingDirectory: root,
}, events)

for event := range events {
	if question, answers, ok := event.Question(); ok {
		fmt.Println(question.Question)
		answers <- agentloop.AgentAnswer{Err: agentloop.ErrInteractionUnavailable}
	}
	if result, ok := event.Result(); ok && result.Response != nil {
		fmt.Println(result.Response.Choices[0].Message.Content)
	}
	if err := event.Err(); err != nil {
		log.Fatal(err)
	}
}

RunAgentLoop closes the event channel when it returns, but it does not close the injected client or tool runtime. Consume message, context-replacement, and compaction events when the host persists conversations. Use agentloop.ScopeTools to apply a role-aware tool catalog. The exact public contract, optional features, and ownership boundaries are documented in the Agent Loop embedding guide.

The minimal tools.NewRuntime does not expose Agent Skill tools. Embedded hosts that need Skill search and automatic hints without the Workspace Archive or Q Library can provide only Search, Save, and Delete through tools.SkillStore and construct the runtime with tools.NewRuntimeWithSkillStore.

Studio guide

Studio is the primary interface for daily Q work:

• Overview starts a personal chat or opens workspace session registration, and lists recent sessions for one-click continuation.
• Sessions shows registered root sessions from every repository as one delegation tree. Add an existing workspace session or create a new root, open child transcripts, and manage the root conversation lifecycle. It also shows current context usage and reconnects to the durable run cursor. Search by session title, project, workspace path, or delegated agent, and collapse groups to keep the tree manageable. On mobile, use Sessions above the conversation to show or hide the session picker. The chat footer selects the session model and reasoning effort. Choices apply to the next turn and survive reload and conversation clear; Default reasoning inherits the global chat setting. Composer shares the chat transcript and input styling while retaining its diagram/HTML artifact panel.
• Files browses directories and files in a chosen workspace, with Raw (syntax highlighting, line numbers, and copy) and Diff modes. Diff keeps the complete file in view, with previous/current line numbers, +/− gutter markers, and colored added/removed rows. It defaults to HEAD versus the working tree; staged and unstaged comparisons are selectable. The session toolbar and Markdown file links open the same viewer beside chat. Child sessions use their delegation worktree; the workspace selector also includes the project's other directories. Deleted files remain selectable through the Git changes list. Text previews are limited to 256 KiB or 4,000 lines; binary/non-UTF-8 files show a notice. The viewer is read-only and hides .git and .q metadata. Raw also works in directories without Git; Diff reports when Git is unavailable.
• Changes owns staged, unstaged, untracked and renamed files, bounded diffs, commit proposal review, split commits, execution, and optional push.
• Councils runs selected models and registered ACP agents through independent answers, anonymous plain-text peer reviews and a chair synthesis. The default is two rounds: first answers, then reviews. Later rounds ask each member to integrate earlier feedback into another review; the chair receives the first answers and every review. Configure one to six rounds in Studio. Create a council without a workspace, or attach one to a workspace or Studio project. Its members and chair can use either a model or an enabled global ACP connection registered in Settings > Providers > ACP. ACP seats use the agent's model defaults. Native seats use Q's read-only repository tools. ACP seats reject edit and command permission requests; the external agent must also enforce its own read-only sandbox. Each ACP seat retains its session across rounds, and resumed runs reconstruct completed conversation text from saved exchanges (external tool state is not restored). Studio processes share the session catalog; configuration, turns, and participant contexts live inside the parent session's council/ directory. Open Council and Composer sessions from Sessions, or create one using New session > New Council / New Composer. Export the full conversation from Studio as Markdown or JSON, including available progress from a turn that is still running.
• Settings owns global and repository model assignments, Gateway and System One, Library and Loom, MCP, LSP, Skills, subagents, ACP bindings, and .qignore. Providers contains API Provider and ACP tabs. ACP connections remain in config.yaml; Subagents retains profiles and external role bindings. The Session model picker also lists enabled ACP connections. Each chat owns its ACP process and conversation, with streamed replies and interactive tool approvals. Agents that offer a model config option expose an ACP model selector, and agents that offer a thought-level option expose a reasoning selector beside it. Changes keep the same live ACP session, persist per chat, and are reapplied on reopening. Model changes refresh the available reasoning levels. Unsupported controls remain disabled and labeled as not exposed. ACP needs no API model configured in Q. Replies show reported cached tokens and cache hit rate, including after reload; missing cache counters remain unavailable rather than appearing as zero. On reopening, Q uses ACP resume/load when available; otherwise it supplies completed conversation text as context without replaying previous operations. Providers > ACP shows installed runtimes. With Node.js and npm available, Codex or Claude Code's ACP adapter installs automatically into Q's user cache on first use. Install adapter optionally prepares it ahead of time; the same preset works in Sessions, Councils, and subagents without restarting Q. Grok uses its native grok agent stdio support. Sign in through the agent's own CLI before chatting.
• Operations shows token usage, active workers, local service health, bounded runtime diagnostics, and usage retention.
• Help lists CLI commands and flags, terminal slash commands and their Studio equivalents, Studio/terminal shortcuts, commit sessions, and recovery guidance. A section index and keyboard-accessible scroll region keep the entire guide reachable.

In chat, Enter sends and Shift+Enter inserts a line break. Use the run controls beside the composer to pause, resume, stop, or redirect active work. Ctrl+K focuses Studio navigation and ? opens Help while focus is outside an editor.

Compatibility terminal client

The bare q client keeps the transcript, active agent progress, input, and status visible together. It remains available while downstream terminal and ACP workflows migrate, but Studio owns configuration, repository review, usage, and help entry points.

Slash commands

Command	Purpose
/changes	Browse current staged, unstaged, and untracked repository changes.
/commit	Generate and review a commit or split-commit proposal.
/sessions	Open the registered root and delegation session tree.
/new	Create and switch to a new session.
/clear	Clear the current conversation projection.
/compact	Summarize older model context without deleting the transcript (TUI and ACP).
/model	Assign models, manage native roles, and configure fallback groups.
/systemone	Configure System One providers, models, and its standalone server.
/gateway	Configure Gateway providers, listener settings, and API keys.
/library	Configure the global Library listener.
/loom	Inspect Loom usage and configure or run garbage collection.
/ignore	Edit workspace discovery rules in .qignore.
/skills	Manage global and workspace Agent Skills.
/lsp	Configure language servers and project roots.
/mcp	Configure external MCP servers and role assignments.
/subagents [list|show <name>]	Manage builtin/custom subagents, external bindings, and ACP connections.
/help	Open the scrollable command and key guide.

Start typing a slash command to filter the catalog. Up/Down selects an entry; Tab or Enter completes it. Enter runs a command that is already complete, and Escape closes the completion popup.

To assign work to an external subagent, bind its profile to an enabled ACP connection in /subagents, join it to the Studio project, and issue a ticket. workspace_members lists joined candidates; ticket_create queues the work for asynchronous System One assignment and execution.

Web Tester invocations run in an isolated ACP process/session with a fixed 15-minute deadline. q automatically selects allow_once, falling back to an offered allow_always; if neither is available, the invocation fails. Assigning the Web Tester role therefore marks that executable as trusted for autonomous verification. Search keeps its read-only permission policy.

Chat keys

Key	Action
Enter / Ctrl+S	Send the current message.
Shift+Enter	Insert a newline.
Ctrl+O	Collapse or expand tool result bodies.
Ctrl+G	Collapse or expand the detailed subagent trace.
Ctrl+L	Clear the current chat projection.
Ctrl+P	Open Gateway settings.
Ctrl+H	Open or close help.
Ctrl+C	Interrupt an active turn; quit while idle.
Esc	Leave the current screen or quit chat.

Assistant messages render as terminal Markdown. Supported streaming providers show reasoning and response text separately; tool calls and agent progress are updated as they run.

Reviewing changes

/changes is a read-only view of the enclosing Git repository. It includes changes that existed before the current q turn, so it is a repository view and not a per-turn audit log. q-owned .q metadata is excluded.

• Up/Down or j/k selects a file.
• Enter focuses its diff; Tab switches between the file and diff panes.
• PageUp/PageDown scrolls vertically; Left/Right scrolls long lines.
• r reloads the repository; Escape returns to chat.

Staged and unstaged patches are displayed separately, even when they cancel one another relative to HEAD. Known languages use Chroma syntax highlighting over addition and deletion backgrounds. Unknown and oversized sources fall back to plain text. Binary files show a notice. Each selected patch preview is limited to 256 KiB or 4,000 lines and is clearly marked when partial. Opening this view does not stage, commit, or modify files.

Delegated work

The default chat loop can use its workspace tools directly and coordinate bounded subagents when a specialist is useful. The manager owns product requirements and the work plan. The senior developer can edit and verify changes directly or assign bounded implementation to a junior developer, then inspect the result and request corrections when needed. The interviewer clarifies consequential questions; the researcher compares approaches. Each role can read relevant workspace evidence directly. Both developers have workspace editing and command tools.

flowchart LR
    U[Request] --> M[Manager]
    M --> I[Interviewer]
    M --> R[Researcher]
    M --> S[Senior developer]
    S --> J[Junior developer]
    J --> S

Loading

The main agent can work directly or issue a project ticket for a joined subagent. Ticket assignment, execution, and Integrator review are asynchronous.

The former /plan command and its approval automation have been removed. Use a project ticket assigned to a joined manager profile for a focused PM task, or ask the main agent to plan and issue tickets in ordinary chat. Existing plan checkpoints remain on disk as legacy data; new work does not resume that workflow.

Commit workflow

Run /commit in chat or launch the standalone UI:

q commit

q uses existing staged changes. If the index is empty, it stages current working-tree changes while excluding q's root .q metadata. It then generates a Conventional Commit or split-commit proposal with the configured commit model. The captured index is verified again before any commit is created.

In the review screen, use Up/Down to select a split message, e to edit, Ctrl+S to save an edit, r to regenerate, Enter to commit, p to commit and push, or Escape to cancel. Push requires an existing upstream.

Providers and model roles

Provider setup supports:

• OpenAI-compatible HTTP APIs, including local servers
• OpenRouter
• xAI/Grok
• Anthropic's native Messages API
• the local Codex App Server using the current Codex login

An ordinary q session supervises a managed Gateway child bound to an ephemeral loopback port. /gateway edits providers and starts a replacement before it activates new settings, so a failed replacement does not discard the running configuration. The standalone q gateway start command is a separate, user-addressable server with its own listener and API-key settings. q studio starts this server alongside its internal Gateway and applies saved provider and listener changes by restarting the standalone server. Both forms record provider-reported token usage in the user-level q usage service.

/model assigns a model to the main chat and specialized roles such as interviewer, manager, research, reviewer, coder, commit, thinker, and librarian. The senior developer uses reviewer; the junior developer uses coder. Press a in the assignment table to create a reusable custom role and d to delete an unreferenced custom role after confirmation. Assignments may reference ordered model groups. A group can fall back after a candidate timeout or transient HTTP 5xx response; user cancellation, tool failure, and validation errors do not trigger fallback.

Q selects Chat Completions or Responses per model. Known native OpenAI, xAI, and OpenRouter Gateway routes prefer Responses; Codex App Server, Anthropic, and unknown compatible endpoints use their existing route. Override a concrete model in /model or ~/.q/config.yaml with model_api_modes, using chat_completions or responses. The Gateway accepts both API routes. Session messages use a common format so saved conversations can continue across a model API change; older Chat Completions sessions migrate when loaded and saved. For Codex App Server, q's minimal agent keeps Q tools visible while excluding inherited private MCP tools such as node_repl from the Codex session.

Global configuration is stored under ~/.q. Workspace model overrides are in .q/model.json. Use the TUI for normal configuration; edit YAML/JSON directly only when automation requires it.

Subagents

Ticket assignment

The default chat loop keeps its workspace tools. To request another subagent, use workspace_members to inspect joined profiles and ticket_create to issue a ticket with scope, acceptance criteria, and report or git execution mode. System One selects a suitable joined member, subject to project and global capacity limits. The Integrator reviews results and pinned Git changes through the ticket workflow. Ticket creation acknowledges durable queuing, not completion.

Direct delegate_list/delegate tools and the /subagent execution command have been retired. Previous child transcripts and completed results remain readable; reopening a parent never starts or resumes a legacy child. Existing saved results can finish an interrupted parent tool response. Historical change requests can still be inspected and cleaned up by their owning parent. See subagent execution for the current contract.

Open /subagents in the TUI to inspect builtin definitions and manage runnable custom profiles. Inner and external execution are shown by the stored kind, not by an ID namespace. Builtin inner entries are fixed definitions; their access label reflects their workspace mutation capability. Pressing e on a builtin external entry changes only its ACP binding; its built-in system prompt remains fixed. Press c to register, edit, test, enable, disable, or delete shared ACP connections. For custom entries, a adds, e edits, and d deletes the selected profile after confirmation. Each list row summarizes its model role, scope, tool state, and delegation grants. ACP connection presets include codex, claude, and grok. The claude preset uses claude-agent-acp, preferring an installed executable or the adapter installed in Studio's Providers > ACP. With Node.js and npm available, opening a missing preset automatically installs its adapter into Q's user cache. Later connections reuse that installation. Install it globally with npm install -g @agentclientprotocol/claude-agent-acp, or use a custom command for another ACP implementation. Connection arguments and child environment variables apply to presets as well. In an editor, Tab or Up/Down selects fields, Enter advances from name and description or opens a scope/kind/role/ACP/tool/delegate picker, Ctrl+S saves, and Esc cancels. Inside the multiline prompt, Enter inserts a newline and arrows move the cursor; Tab moves to the next field; Shift+Tab, Esc, or Ctrl+Up returns to the previous field without discarding the prompt. Scope and Role cycle with Left/Right or Space; Enter opens their selection list. Tools and Delegates open searchable lists; Space or Enter toggles selections. Tab/Shift+Tab leaves a list for the next/previous field, and Esc returns to that field. Ctrl+S or F2 saves from any editor field or open selection list. You can also Tab to the final Save action and press Enter. Validation errors keep the draft available for correction. The system prompt supports multiple lines.

A profile is either inner or external. An inner profile combines a system prompt, an explicit tool list, directly callable subagents, and a native model role. Every inner subagent also receives task_start, search_skills, and get_skill as fixed tools. A custom role uses the existing model, model-group, and reasoning settings in ~/.q/config.yaml. Manage role assignments from /model: a creates a custom role and d deletes one after confirmation. Built-in native roles can also be selected; selecting one uses its model settings without invoking its built-in workflow. The names default, embedding, search, external_web_tester, and built-in role names are reserved and cannot be registered as custom roles.

Profiles are YAML files in ~/.q/subagents/ or <workspace>/.q/subagents/. A workspace profile replaces the entire global profile with the same name. Changes apply on the next invocation. Existing profile and role names are fixed when editing. Changing a profile's scope moves its file without overwriting an existing profile at the destination. A referenced custom role must be reassigned in the known global and current-workspace profiles before deletion from /model. A profile referenced by another profile's delegates cannot be deleted from the TUI until that grant is removed.

An external profile instead stores an ACP connection, a system prompt, and whether the connection may mutate the workspace. It does not select a q model role, q tools, or delegates. ACP has no system-message field in its session-creation contract, so q prepends the stored system prompt to the first ordinary ACP prompt before the explicit request. Disabled or missing connections make the profile unavailable without deleting it.

version: 1
name: code-reader
description: Explain the requested code.
kind: inner
role: advisor
system_prompt: |
  Read the requested code and explain its behavior with concrete file references.
tools:
  - list_directory
  - read_file
delegates: []

version: 1
name: browser-check
description: Verify browser behavior through an ACP agent.
kind: external
agent: browser
system_prompt: |
  Verify only the requested browser behavior and report observed evidence.
mutates_workspace: true
tools: []
delegates: []

TUI and ACP support /subagents list and /subagents show code-reader. Join a profile in Projects and issue a ticket to request its work. The public builtin IDs are builtin/interviewer, builtin/manager, builtin/senior-developer, builtin/junior-developer, builtin/research, builtin/web-search, and builtin/web-tester. The junior developer can be joined to a project and assigned a Git ticket. The latter two have kind: external; other external agents use their normal global/... or workspace/... profile ID. Bare /subagents opens the profile UI in the TUI and lists all available definitions in ACP. Creation, editing, and deletion use the TUI or profile files. Pass all necessary task context in the request: the child does not automatically inherit the parent conversation. tools: [] and delegates: [] grant nothing. Delegation grants use canonical IDs (builtin/..., global/..., or workspace/...). Unavailable tools, roles, or delegates produce an error before the model runs.

Inner ticket workers share the host-provided task_start and task_complete lifecycle. External workers use their existing ACP invocation adapter and Loom capture. Native builtins can inspect workspace members and issue followup tickets; custom profiles must allow the corresponding ticket tools. Additional work is assigned asynchronously rather than invoked through a nested direct tool call. A task result keeps its short conclusion in summary and may include a Markdown report up to 256 KiB for detailed analysis, design rationale, review notes, or research synthesis. Large results use the existing Loom receipt and retrieval path.

Sessions, history, and workspace knowledge

Each workspace can hold multiple UUID-based sessions. The startup picker shows their titles and recent activity. Press d on a selected inactive session, then y to delete it (n or Esc cancels). The current session and sessions owned by another process cannot be deleted. Deletion removes the conversation projection and resumable checkpoint, but leaves durable Workspace Memory archive records.

One process owns a selected session, while a different session in the same workspace may be opened concurrently. Session locks coordinate conversation state; they do not serialize edits to project files.

The current transcript and the compacted request context are persisted separately. When context metadata is available, q compacts model context while leaving the complete visible transcript intact. Workspace Memory stores durable messages, tool activity, failures, lifecycle events, and search indexes.

Issues and tickets belong to Studio projects (one project may contain several directories). Library stores their originals centrally, with workspace and explicit global text/semantic/hybrid search. Bodies and replies have stable IDs, revision history and paginated reads. Record verified lessons explicitly in issues/comments; automatic learning, Thinker, Librarian, learn, request_learning, and proposition APIs have been removed. Old learning data is inert and cannot restart background work.

Each project has one protected Manager session, using either Q's API loop or ACP. Clear retains its identity, model choice, work items and review inbox. The Tickets board uses To do / In progress / Done. Join existing subagent profiles to a project. Issuing a ticket automatically queues it for assignment; System One checks joined candidates before every execution; failed selection remains visible as assignment waiting. Native workers reuse GeneralRunner; mutating native/ACP workers use the existing isolated Git worktree/MR flow. Results wait for manager review. Feedback continues the worker conversation; report acceptance or a successful pinned Git merge marks the ticket done. Interrupted work is fenced and uncertain side effects are not blindly replayed.

See Session Store notes, Workspace Memory, and Global Library for storage and ownership details.

Tools and integrations

Builtin workspace tools

The model can read and edit files, write complete files, list and manipulate paths, and launch asynchronous shell commands. File operations are jailed to the workspace and hash-anchored edits reject stale context. Shell commands start inside the workspace but are not an OS sandbox.

Every non-Loom tool result is captured before it returns to the model. Small results remain inline; large results return a bounded loom_ref receipt. The model can inspect or transform selected artifacts with loom_inspect, loom_read, and restricted loom_eval.

External MCP servers

Use /mcp or q mcp to configure stdio or Streamable HTTP MCP servers and assign them to individual roles. Imported names are namespaced to prevent collisions, and each result passes through the same Loom capture boundary. Environment and header settings refer to environment-variable names rather than storing credential values inline.

Agent Skills

q implements the portable SKILL.md Agent Skills format as an on-demand retrieval layer. It keeps the full catalog and skill bodies out of the base prompt. For roles with both skill tools, a new user turn or new information from task_start and ask_to_user triggers a bounded metadata search that adds up to four previously unseen candidate skills to the new context:

new user/task information
  -> BM25 or hybrid metadata search
  -> bounded candidate hints
  -> get_skill for an applicable candidate
  -> full SKILL.md/resource in model context

Candidate metadata is not treated as an instruction: the model must call get_skill before following a skill. Automatic search failure never blocks the turn, and roles with skill tools can still call search_skills whenever later work needs more guidance. Already hinted or loaded skill IDs are not suggested again in the same context.

When System One settings have been saved, q retrieves 32 hint candidates, scores every candidate in one agent_skill_decision request, and supplies the top eight for task_start or the top six for other contextual triggers. Without System One reranking, task_start retrieves at most twelve candidates and supplies at most six. A direct search_skills call retrieves and scores 32 candidates and returns at most 20, or the smaller requested limit. If the decision request fails, q keeps the original search order and reports a non-blocking warning.

Without an embedding model, retrieval is BM25-only. With one, q combines BM25 and HNSW vector results; assigning a new embedding model rebuilds and backfills the vector projection. Each skill embeds its name, description, and individual tags separately. Vector projection relevance favors description (4), tags (3), then name (2); BM25 field boosts favor name (4), tags (3), then description (2). Existing combined skill vectors are backfilled into separate projections on the next indexing run. Global and workspace results receive no scope bonus; when both bounded result sets contain the same skill name, the workspace hit wins, and total is computed after merging and de-duplication but before applying the requested limit.

Dynamic hints are appended to the current user message or the new tool result, never inserted ahead of an already-sent conversation prefix. The visible transcript retains the original user text. This keeps earlier prompt content eligible for provider prefix caching, although individual cache hits remain provider-managed.

Skills are discovered, in increasing precedence, from:

~/.agents/skills/
~/.q/skills/
<nearest-git-root>/.agents/skills/  # when distinct from the active workspace
<workspace>/.agents/skills/
<workspace>/.q/skills/

The Git-root lookup lets a q session started in a repository subdirectory use the repository's portable skills without expanding the session's file-tool jail. While q is running, skill use triggers a workspace reconciliation when the previous check is at least 30 seconds old. Frontmatter name remains the canonical skill name but does not have to match the directory, and description is optional.

/skills can clone, fast-forward, remove, and reindex q-managed global or workspace skills. See Agent Skills for validation, contextual hint bounds, indexing, prompt placement, and tool access rules.

Workspace instructions

q automatically loads a workspace-root AGENTS.md as a bounded developer instruction. Structured tool paths activate nested AGENTS.md files from the root toward the target; the primary agent pauses the first affected tool batch so it can review newly loaded rules before retrying. See Workspace instructions for precedence, subagent behavior, path detection, and safety limits.

Language servers

/lsp or q lsp configures global language-server profiles and workspace project roots. q exposes diagnostics, hover, definitions, references, document symbols, and workspace symbols as read-only tools. It rejects workspace/applyEdit and does not expose rename, formatting, code-action execution, or arbitrary server commands.

See LSP integration for discovery, routing, synchronization, and failure behavior.

Discovery and .qignore

.qignore filters directory discovery and root listings. It supports comments, negation, root anchoring, directory suffixes, and *, **, and ? wildcards. It is a discovery aid, not an access-control boundary: a tool can still read an explicitly requested in-workspace path.

ACP and standalone services

ACP agent mode

Run q as an Agent Client Protocol server over stdin/stdout:

q acp [--root <workspace-path>]

ACP mode shares q's sessions, workspace tools, delegation, external Search/Web Tester, and commit workflow. /commit uses form elicitation when available. Otherwise, approval uses numbered actions, and agent questions consume the next message as a free-form answer. Git changes still require explicit approval.

Client-provided stdio and Streamable HTTP MCP servers are scoped to their ACP session. SSE transport is not supported.

q advertises ACP embedded-context support and preserves resource URI, MIME type, annotations, and contents when sessions are replayed. When the TUI is connected to an external ACP agent, @relative/path attaches an in-workspace file; @"path with spaces" is also accepted. q embeds the file when the remote agent advertises embedded context and otherwise sends an ACP resource link.

Workspace MCP server

Expose q's builtin workspace tools to another MCP client:

q-mcp -root C:\path\to\workspace

q-mcp uses stdio and applies the same root jail and Loom limits. Project issue and ticket tools are supplied by the host-bound q library mcp bridge.

Standalone commands

Command	Purpose
q gateway	Configure the Gateway listener, API keys, and providers.
q gateway start [--host <ip>] [--port <port>]	Run the OpenAI-compatible Gateway.
q studio [--host <ip>] [--port <port>] [--no-open]	Start the embedded Studio web interface. Defaults to 127.0.0.1 and a random port.
q library	Configure the global Library listener.
q library start	Run the global Library as a dedicated foreground service.
q memory	Keep Workspace Memory running independently of a TUI.
q usage	Open Studio Operations for usage, workers, services, logs, and retention.
q commit	Run the interactive terminal commit session for the current repository: generate, review, edit, and approve proposals.
q model	Configure model and role assignments.
q systemone	Configure System One providers, models, and its standalone server.
q systemone start [--host <ip>] [--port <port>]	Run the standalone System One API server.
q subagents	Manage subagents, external bindings, and ACP connections. (q agents is a compatibility alias.)
q mcp	Configure external MCP servers.
q skills	Manage Agent Skills.
q lsp	Configure language servers.
q ignore	Edit .qignore.
q help	Open Studio Help.

System One runs independently of Q's chat Gateway. In q systemone, use ↑/↓ or Tab to select a setting, Enter to edit it, a to add a provider, and d to remove the selected provider. Valid changes are saved as they are made, including model selections. Providers contain an endpoint and an optional API key environment variable name; q reads provider keys from the environment and does not write them to systemone.json. Older inline provider keys are ignored; set the named environment variable to keep authenticating with the provider. The old field is removed on the next save. The API keys screen uses a to generate a client key and r twice to revoke one. Generated keys are shown once; only their hashes are stored. With no active keys, q systemone start accepts requests without authentication. The representative default_model and optional agent_skill_decision role assignment are separate provider-id/model-name values; clear the role assignment in its model picker to use the default. Press Enter on either assignment to pick from all configured providers. The listen host, port, and client key records are stored in the same settings file. Existing single-provider settings are converted when loaded and saved in the new format on the next change.

q systemone start serves GET /v1/models and POST /v1/systemone. Discovered models and routed requests use provider-id/model-name; a model name without a provider ID goes to the provider named by default_model for compatibility. Each provider may serve multiple models. The server listens on 127.0.0.1 with a random port by default. Clients send an active System One API key as a Bearer token. With no active keys, requests are accepted without authentication, including on non-loopback hosts. Existing single server keys remain active until revoked in the API keys screen. --host and --port override the saved listen address for one run.

Ordinary q processes automatically ensure Workspace Memory, the global Library, and token Usage storage are available when needed. Run the standalone service commands when their lifetime should not depend on an interactive session. The internal data services bind only to a loopback IP address and accept local HTTP requests without bearer authentication.

The standalone Gateway initially binds to 127.0.0.1:0. If it has no active API keys, authentication is disabled. Do not expose a no-key Gateway on a non-loopback address unless the surrounding network already enforces access. Calls without Q usage metadata appear under the bounded gateway role. A Q client can opt in to role/event-ID forwarding; those headers are telemetry classification, not authenticated caller identity, and the Gateway removes them before provider dispatch.

q studio starts a user-level server on 127.0.0.1 with a random port and opens its embedded Svelte interface. --host selects a listen IP, --port selects a fixed port, and --no-open leaves the browser closed. A non-loopback host exposes Studio without built-in HTTP authentication, so use one only within a trusted, firewalled network or behind an authenticated reverse proxy. Studio does not treat the launch directory as a workspace. Sessions start from a user-level registry of root sessions. Add a repository directory, choose one of its persisted sessions or create a new root, then navigate its delegated child sessions as a tree. Each root keeps its repository as execution metadata. The chat persists response, reasoning, tool, agent activity, and context usage events so a browser can reconnect without owning the run lifetime.

Studio also provides the application shell and global Settings for runtime, context, Loom, and service listeners. Changes save automatically through the same validated stores used by the TUI. Gateway providers and global model assignments use discovery-backed editors. System One providers, decision model routing, listener settings, and server API key lifecycle are also available; provider authentication uses environment variables only. Workspace model overrides, MCP/LSP management, session questions, durable event reconnection, turn control, repository change review, and delegated worktree status are available in Studio. Manual change-request review controls, the remaining run graph, and long-running task work are tracked in the Q Studio blueprint.

Data and configuration

Personal state

Path	Purpose
~/.q/config.yaml	Main model, roles, context, Loom, and LSP configuration.
~/.q/providers.json	Managed Gateway providers and model metadata.
~/.q/gateway.json	Standalone Gateway listener and key metadata.
~/.q/systemone.json	System One providers, decision model routing, listener, and server API key metadata.
~/.q/systemone.key	Private master key used only to verify System One server API keys.
~/.q/library.json	Global Library loopback listener settings.
~/.q/workspace-memory.json	Workspace Memory settings.
~/.q/usage.json	Token Usage service loopback endpoint settings.
~/.q/mcp.json	External MCP profiles and role assignments.
~/.q/studio-sessions.json	Registered Studio root sessions and their workspace locations.
~/.q/chats/chat-*/.q/sessions/<session-id>/	Default private workspace sessions for personal chats, Council, and Composer; explicit storage roots are also supported.
<workspace-root>/.q/sessions/<session-id>/session.json	Canonical session with explicit interaction, council, or composer type.
<workspace-root>/.q/sessions/<session-id>/council/	Council configuration, turn checkpoints, and internal participant contexts.
<workspace-root>/.q/sessions/<session-id>/composer/ and docs/	Composer presentation state and managed D2/HTML artifacts inside its session.
~/.q/worktrees/<repository-hash>/<invocation-id>/	Linked Git worktree leases for mutating delegated sessions.
~/.q/systemone.json	System One providers, model assignments, listener settings, and client key hashes (saved with private file permissions).
~/.q/systemone.key	Private master key used to verify managed System One API keys.
~/.q/skills/	q-managed global Agent Skills.
~/.q/logs/studio/	Rotating Studio diagnostics; 25 MiB per file, 1 GB total, seven-day retention.
~/.q/usage/usage.sqlite	Recent token-only events and all-time daily rollups.
~/.q/usage/archive/	Daily Parquet archives for raw events older than 90 days.
~/.q/logs/model-usage/	Legacy JSONL import source; successful import does not delete it.

Gateway authentication master keys are stored separately under ~/.q. Global Library and Workspace Memory do not create or require authentication keys; legacy library.key and workspace-memory.token files are ignored. Prefer environment variables for provider and MCP credentials. POSIX permissions are restricted by q; Windows file modes do not manage ACLs.

Workspace state

Path	Purpose
.q/sessions/<uuid>/session.json	Transcript, compacted context, title, and task lifecycle.
.q/sessions/<uuid>/delegations.json	Bookmarks linking this session to its delegated child calls.
.q/sessions/<uuid>/delegates/<invocation-id>/	Child session, execution state, and nested delegation tree.
.q/sessions/<uuid>/plan-execution.json	Legacy plan checkpoint, retained for existing data.
.q/plan-executions/	Legacy execution snapshots.
.q/model.json	Workspace model-role overrides.
.q/lsp.json	Workspace LSP roots and overrides.
.q/data/ and .q/index/	Durable history records and derived indexes.
.q/loom/	Content-addressed tool artifacts and GC metadata.
.q/skills/	q-managed workspace Agent Skills.
AGENTS.md	Automatically loaded repository instructions; nested files scope descendants.
.qignore	Discovery exclusions.

The JSON records are the source of truth; Bleve and HNSW data are derived and rebuildable. Loom garbage collection protects references from active session projections and saved records, subject to its configured grace period.

Runtime layout

An interactive q process coordinates components with separate ownership:

Editable source: docs/architecture.drawio.

Component	Lifetime and responsibility
TUI	One selected session, chat lifecycle, and user interaction.
Managed Gateway child	Provider aggregation for that q process on a private loopback endpoint.
Workspace runtime	Root-scoped tools and local LSP sessions.
Workspace Memory	Durable records and Bleve/HNSW indexes for leased workspace roots.
Global Library	Global skills, workspace issues/tickets, search projections and coordinator state.
Usage service	Token-only SQLite hot store, daily rollups, Parquet archive, and local dashboard.

This separation allows several q processes to share durable services without sharing a chat session or provider conversation lifecycle.

Development

The repository's go.work connects the root module, q's maintained ACP SDK fork, and its generator. Keep workspace mode enabled when developing them together.

go test ./...
go vet ./...
task test
task build
task dist:check

Install the Studio development dependencies with task studio:install first. task test also tests the nested ACP modules, checks generated binding drift, and checks Studio types. See ACP fork maintenance before updating or publishing the fork.

Studio browser regressions run separately:

npm --prefix ./studio/frontend run test:e2e:install
task studio:test

The browser suite builds and serves the embedded UI with disposable settings, workspaces, and a local model fixture. It needs no provider API keys and leaves your running Studio and user configuration untouched. See Regression and integration tests for covered workflows and failure diagnostics.

Design notes

• Q Studio blueprint
• Q Studio TUI migration
• Agent Loop embedding guide
• Architecture refactoring roadmap
• Embedded Agent Loop public API
• Agent Skill Store decoupling
• Agent invocation runtime
• Delegated subagents
• Delegation session recovery
• Model API modes and portable sessions
• Model output limits and response recovery
• Subagent architecture
• Context compaction
• Session Store
• Workspace Memory
• Global Library
• Agent Skills
• Workspace instructions
• LSP integration
• Model token usage tracing
• Gateway usage attribution
• Model Usage storage and dashboard