Skip to main content

Get started

Install Compositor, connect a model, and run a task. The native application runs on Linux with glibc 2.38 or later and macOS, on x64 and arm64.

Install​

curl -fsSL https://raw.githubusercontent.com/Neko1313/agent-compositor/main/install.sh -o install-compositor.sh
sh install-compositor.sh
export PATH="$HOME/.local/bin:$PATH"
compositor --version

The installer verifies archive checksums and retains your settings and sessions. Run it again to update. You can also download and extract an entire archive from GitHub Releases. Keep the executable beside its bundled plugin and dependency directories.

Connect a model​

Current development builds open Get started on a fresh interactive launch without an explicitly configured model. Published 0.7.4 predates this guide. The guide itself runs locally without a model or inference server. You can skip it and reopen it with /setup or Settings → Setup guide. Skip is remembered privately for your user; plain/headless runs and explicit session resumes do not open it automatically. If the saved setup status is malformed or from an unsupported version, startup continues and the guide warns about it. The existing file is left untouched until you explicitly finish or skip the guide. An invalid saved model selection is ignored at startup; it does not prevent the guide from opening when no other model has been configured. Saving a new model selection replaces that invalid selection.

Set up model lets you choose an existing connection or create one using five fields: profile ID, endpoint, model ID, optional API key, and save scope. Keys are masked and kept in the private credentials file. Advanced settings opens the full editor. Saving does not issue a completion or test the connection; model discovery/testing is an explicit action.

Start compositor and open Settings, or use /settings, to add a provider connection. Select a model and supply credentials when your provider requires them. Ollama, OpenAI Responses, Anthropic, Gemini and compatible gateways have connection presets. A running Ollama endpoint or an accessible external model service is required to answer ordinary prompts.

You can also select a compatible endpoint for one launch:

AGENT_BASE_URL=http://127.0.0.1:11434/v1 AGENT_MODEL=your-installed-model compositor

Replace your-installed-model with an actual model ID exposed by that endpoint. Use provider settings for private credentials, profile selection and network configuration.

Run your first task​

Launch from the project you want to work in:

cd /path/to/your/project
compositor

Enter a task such as “Explain this project's structure and entry points.” Enter submits or queues a message; Tab steers a running turn. Ctrl+C interrupts the current turn. Tools that need permission show their concrete action for review. Use /history to find and resume saved conversations.

To work with another project in the same session, use /workspace add PATH or start with --add-dir PATH. Read workspace access before granting more scope.

Enable useful extensions​

In the setup guide, Choose recommended tools asks what work you plan to do and lets you select optional project checks, test reports, change review, web research, a resource monitor, side conversations and automatic approval review. Coding initially suggests project checks; research suggests web access. The resource monitor and side conversation and approval review are unchecked until you select them. The monitor does not call a model; side conversations require agent-hub and use the configured model. If agent-hub is unavailable, the guide warns before and after selection. Check disabledPlugins and any enabledPlugins allowlist in agent-compositor.json, enable agent-hub there, and restart the app; /btw --once remains available for an independent one-shot answer without a side-conversation window. The one-shot answer also uses the configured model. Approval review is opt-in for each session: after installing it and applying plugin changes, use /auto on to enable model-assisted review and /auto off to return to manual approvals. Reviews use a model and uncertain or high-risk actions can still require your decision. See auto review. Only checked additions are installed if needed and enabled for the project. View tool status shows which suggested plugins are currently active, have been selected but need changes applied, remain active until reload, or are not active. The list reflects application state and does not contact a model. Downloads may be needed, and existing installations, versions and active plugins are retained. The guide does not change explicit plugin restrictions or tool permissions. Restricted recommendations are unchecked, explain the relevant enabledPlugins or disabledPlugins setting, and are not installed even if selected. Other selected recommendations can still be installed. Use Apply plugin changes before Start chatting; reload waits for an active agent when necessary. If you disable a selected plugin through Extensions before applying changes, the open guide in that session updates without taking focus and no longer waits for that plugin to load. When the guide is opened or refreshed, it also detects recommended plugins enabled outside the guide that are not loaded yet, including selections made in another session. Completion checks the current state even if the open view has not refreshed, and refreshes it when changes are pending. If a disabled recommended plugin is still active, apply changes to unload it before completing setup. Skip remains available if a plugin cannot load or unload. If a recommended tool is still pending after reload, the guide says so; check the reload result for errors or open Extensions to change the selection. Failures remain visible so you can retry or continue without optional tools. If a download succeeds but enabling fails, the guide reports the installation and the enable error; inspect the current state in Extensions before retrying. No model is invoked by these setup steps. If an installation is interrupted, the guide stops before starting the next selection. An operation already in progress may have completed; reopen /setup or Extensions to inspect what was installed or enabled before retrying.

Since host v0.4.0, bundled filesystem plugins start inactive. Installation and activation are separate, and /reload applies plugin changes between turns.

/marketplace
/extensions install web@agent-compositor --project
/extensions enable web --project
/reload

The web plugin adds search and page fetching. Other optional packages include Callix for code navigation, Monty for generated Python, workflows, and the Ghost companion. Browse their setup and requirements.

Use --user for shared user defaults. Project selections override user defaults; a configured capability ceiling still applies. Monty's optional worker requires Node.js 22 or later; the core native executable starts without Node.js or Bun.

Run without the terminal UI​

compositor -p "Explain this project" --output-format json

Text, JSON and streaming JSON output are supported. See the generated CLI reference for flags and the agent feature guide for limits and configuration.

Troubleshoot setup​

  • A connection error: verify the endpoint, selected model, credentials and proxy in Settings.
  • A missing command or tool: confirm its owner is installed, enabled in the effective scope and reloaded.
  • Missing native graphics: the companion needs terminal protocol support; a compact status is the fallback.
  • Source development: use the contributor guide instead of the native installer.