Projects & sessions

Projects

A project points to a folder on your machine. The project path scopes file browsing, file mentions, terminal working directory, git status, language-server context, and agent file tools.

The left sidebar lists projects. Each project can be collapsed, archived, or expanded to show its sessions. Open project adds another folder to the sidebar.

Sessions

A session is a conversation thread inside a project. Sessions keep their own message history, plan artifacts, tool calls, usage, file-change history, live todos, runtime kind, and dispatch status.

Use a new session when the topic changes, when you want to try a different runtime, or when a task dispatch creates an isolated worktree branch.

Native and external runtimes

New Thread starts the native AgentsOS runtime. If Settings detects external ACP agents, the project menu can also create Codex, Claude Code, or OpenCode threads. External sessions show a runtime icon in the sidebar and a runtime badge in the editor.

External threads use the external agent's own config controls when available. Native threads use AgentsOS providers, models, permissions, plan mode, MCP, skills, notes/tasks tools, subagents, and local file tools.

Task dispatch sessions

Dispatching a task creates a worktree-backed session on a generated or chosen branch. These sessions are marked with a Dispatch chip. After the work is committed and clean, the right sidebar shows Merge Worktree.

If merge conflicts occur and auto-dispatch is enabled, AgentsOS can create a follow-up resolver session for the target branch.

Archiving

Project and session archive buttons remove items from the active sidebar view. Usage history can still show deleted sessions with a Deleted badge when their usage records remain in the local database.