Skip to main content

Agent Sessions

Experimental

Agent sessions are opt-in in this release. Enable them under Settings → Experimental → Agent sessions.

LaraEnv can run installed Claude Code, Codex, Kimi, and OpenCode CLIs inside the existing Terminal Workspace. Sessions are organized as project → working copy → session, while their terminals stay open as ordinary tabs.

Start a session​

Open Terminal, expand the Agents navigator, and select New. Search for a project, choose an installed provider, then choose where it should run.

You can also use the Command Center: type a project and provider, such as cotesaude claude, cotesaude codex, or acme kimi. This quick action starts in the current checkout; use the full launcher when you want a branch or worktree.

LaraEnv detects providers from their local command-line executables and displays the installed version. It does not install, authenticate, or bypass the security controls of those tools.

Choose the working copy​

The choice is explicit on every launch:

  • Current checkout — the default. Runs in the project folder exactly as it is and performs no Git or routing change.
  • Switch main checkout — switches the project's existing folder to a branch you select. LaraEnv refuses unsafe switches when the checkout is dirty or is shared by another live agent.
  • Isolated worktree — creates or reuses a separate checkout under LaraEnv's managed worktree directory. This is optional, not a requirement for using agents.

Multiple agents in the current checkout share the same files. LaraEnv warns when another live session already uses that checkout, but you decide whether to continue.

Domains and worktrees​

Creating a worktree does not change Nginx, the Windows hosts file, or the main project URL automatically. If a worktree needs to serve the app, choose one of these separately:

  • Keep the canonical project domain on the main checkout.
  • Explicitly assign the canonical domain to the worktree.
  • Create a separate editable preview hostname for the worktree.

For proxied Node/Vite applications, a worktree preview also needs its own port so the main and isolated servers do not collide. LaraEnv validates routing changes and can restore the canonical domain to the main checkout.

Manage sessions​

The collapsible navigator separates Active, Recent, and Archived sessions and supports text search. From a session you can focus its tab, rename it, stop it, archive its LaraEnv metadata, and resume it when the provider has a verified conversation identifier.

Closing the navigator does not stop any terminal. Session metadata is stored separately from provider-owned conversation history.

Restoration and usage​

  • Live terminal layouts are persisted across navigation and application restarts.
  • Cold conversation resume is provider-dependent. LaraEnv validates the provider's local metadata before offering resume; if it is missing or stale, start a fresh session instead.
  • The bottom status strip displays usage only when LaraEnv has a supported local reader. Unsupported, unavailable, stale, or signed-out states are identified instead of estimated.

Current limitations​

  • Agent tabs cannot be detached into a second LaraEnv process yet. Local, project, and SSH tabs keep their normal detach support.
  • Provider capabilities vary by installed version, especially resume and usage reporting.
  • Notifications are kept in LaraEnv's in-app inbox. Native Windows toast delivery is temporarily unavailable while it is redesigned for signed builds.
  • Do not disable or reset the experimental feature while live agents or managed worktree dev servers are running; LaraEnv blocks this to avoid orphaning resources.