Projects & Sessions

The agent organizes work into projects and sessions:

  • Project — a directory on your machine. All sessions within a project operate in that directory's scope.
  • Session — a conversation thread. Messages, tool calls, and generated files are persisted in SQLite.

Projects

Creating a Project

In the agent sidebar, the Projects column has an inline form: enter a name and a filesystem path, then press Enter. The CLI validates the path exists.

The agent can read/write files and execute shell commands within the bound directory tree. Each project maintains its own set of sessions.

Studio Binding

Projects can be linked to Aexol Studio projects. When bound, the CLI writes .aexol/aexol.jsonc into the project root. This lets remote Studio tools auto-inherit context from the local project.

Project API

GET    /api/projects              → list projects
POST   /api/projects              → create (name, path)
PATCH  /api/projects/:id          → update name or path
DELETE /api/projects/:id          → delete
POST   /api/projects/:id/bind-studio → link to Studio project

Sessions

Creating a Session

Select a project, click + New Session. The session is immediately linked to the project.

Active Session#3 · 2 min ago

my-nextjs-app

/Users/artur/code/my-nextjs-app

Messages
42
Files Touched
17
Duration
24m

Session persists across browser refreshes and machine restarts. Messages and file history stored locally in SQLite.

Session Lifecycle

  • Messages persist in local SQLite across browser refreshes and machine restarts
  • The agent auto-titles sessions after the first assistant turn completes (via session_renamed event)
  • Sessions can be forked via "Fork & Compact" — copies all messages into a new session and triggers compaction on the first turn

Current Turn Replay

If you disconnect mid-response (browser close, network drop):

  1. The agent continues processing locally
  2. On reconnect, the relay sends session_ready.currentTurn — a snapshot of all events that happened
  3. The UI replays: text deltas, tool calls, tool results, thinking blocks

Multi-Tab Support

Multiple browser tabs subscribed to the same machine receive the same event stream. Sending a message from any tab updates all tabs.

Session API

GET    /api/projects/:id/sessions          → list sessions for project
POST   /api/sessions                       → create (projectId)
GET    /api/sessions/:id                   → full detail with messages
PATCH  /api/sessions/:id                   → rename (title)
DELETE /api/sessions/:id                   → delete
POST   /api/sessions/:id/fork              → fork & compact
GET    /api/sessions/:id/memory            → memory status
GET    /api/sessions/:id/memory/details    → observation/reflection detail
POST   /api/sessions/:id/compact           → trigger manual compaction

Next Steps