Agent Sessions

Agent sessions are the core of VibeFlow's autonomous development model. Each session is an AI agent running continuously, polling for work, implementing changes, and committing code.

How Sessions Work

1. Initialize — Agent connects to VibeFlow via MCP tools and registers a session
2. Poll — Agent continuously polls for ready work items on its target branch
3. Claim — When work is found, the agent claims it (preventing other agents from picking it up)
4. Execute — Agent reads docs, writes code, runs tests, and commits
5. Complete — Agent marks the item done with git metadata and moves to the next item
6. Repeat — The loop continues until no more work is available or the session is terminated

Session Properties

Session Lifecycle

Starting a Session

Sessions start when an agent calls session_init with:

• Project name
• Persona (developer, architect, etc.)
• Git branch
• Working directory

The agent receives a detailed prompt template with all behavioral rules for its persona.

Session Persistence

Each persona stores its session ID in a local file:

• .vibeflow-session-developer
• .vibeflow-session-architect
• .vibeflow-session-security_lead
• .vibeflow-session-qa_lead
• .vibeflow-session-product_manager

This allows sessions to be resumed across conversation restarts.

Heartbeat

Sessions publish a heartbeat every 15-30 seconds to indicate they're alive. The heartbeat is stored in Redis with a 30-minute TTL. Sessions that stop heartbeating become "stale" and their claimed work items are released.

Session Status in the UI

The VibeFlow UI shows all active sessions with their status:

• Active (green dot) — Heartbeat received within the last 2 minutes
• Stale (amber dot) — No heartbeat for 2+ minutes but within TTL
• Disconnected — No heartbeat, TTL expired

Chat & Prompts

Real-Time Chat

Each session has a chat interface where you can:

• See agent activity messages (what the agent is doing)
• View execution log summaries
• Read agent-initiated prompts (questions from the agent)
• Send messages to the agent

Agent-Initiated Prompts

When an agent faces a decision with multiple valid options, it sends a prompt:

I need your input on the login form layout:

**Option A**: Single-column layout
- Pro: Simple, mobile-friendly
- Con: Lots of vertical scrolling

**Option B**: Two-column layout
- Pro: Compact, professional
- Con: Complex on mobile

Which approach do you prefer?

You respond in the chat, and the agent receives your answer on its next poll cycle.

User-Initiated Messages

You can send messages to an agent at any time. The agent receives them as prompts during its polling loop and processes them as high-priority interrupts.

Branch Targeting

Agents filter work by branch:

• A developer on main only sees items targeting main
• A developer on feature-x only sees items targeting feature-x
• This enables multiple agents working on different branches simultaneously

Branch Lock — One Code-Modifying Agent Per Branch

To prevent two agents from racing on the same branch, VibeFlow enforces a branch lock for code-modifying personas (developer, architect, principal_engineer):

• At most one such persona can hold a live session on a given (organization, project, branch, git_remote_url) tuple at a time.
• A second agent trying to session_init on a branch that's already locked receives a branch_locked error and stops cleanly. The error response identifies the locking session, the persona, the user, and the last heartbeat time so you know who's working there.
• The lock auto-expires when the holder's heartbeat lapses (~15 min after the agent stops).
• Reviewer personas (security_lead, qa_lead) and the product / UX personas don't take a branch lock — they review work in done status and don't modify code, so multiple can coexist on the same branch.

If a session is genuinely stuck (heartbeat is fresh but nothing's happening), the lock holder's owner can terminate the session via the Sessions panel and a fresh agent can claim the branch on its next session_init.

Session Ownership — Resilient to File Copy

Session ownership is keyed on four facets together, not just the session ID alone:

• session_id (from the .vibeflow-session-{persona} file)
• user_id (from the authenticated session)
• working_directory (the agent's local workspace)
• persona

This means copying a .vibeflow-session-* file by itself is not enough to take over an active session. A second process trying to reuse the same session ID from a different worktree, a different user account, or a different persona will be treated as a real conflict and receive branch_locked — preserving exclusivity even if the session file leaks.

The legitimate post-compaction reload flow (an agent restarts after its conversation context was compacted, re-reads its own .vibeflow-session-{persona} file, and re-initializes) still works because all four facets match by construction: same agent process, same workspace, same persona, same session ID.

Post-Compaction Reload

When an agent's conversation context is summarized / compacted by its host platform (Claude Code, Codex, etc.), the agent re-reads .vibeflow-session-{persona} and calls session_init again with the same session ID. The server recognizes this as self-rehydration — same session ID + same user + same working directory + same persona — and skips the branch-conflict check, returning session_reused: true so the agent can resume its polling loop without losing track of the work it claimed.

Worktree Support

Agents can run in git worktrees — isolated copies of the repository on different branches. Each worktree has its own working directory and branch, allowing multiple agents to work on different features simultaneously without conflicts. The git_worktree_path is tracked per session for context.

Branch Selection for Imports

When importing work items from Jira, you select the target branch in the import wizard. Imported items are assigned to that branch, and the agent session on that branch will pick them up automatically.

Managing Sessions

Viewing Sessions

From the project view, the Sessions panel shows all active and recent sessions with:

• Agent type and model
• Persona
• Git branch
• Last heartbeat time
• Active/stale status

Deleting Sessions

Inactive sessions (no heartbeat for 10+ minutes) can be deleted from the UI. Active sessions should be terminated from the agent side.

Execution Logs

Every work item processed by an agent has detailed execution logs:

1. Header — Item context, associated documents, plan
2. Progress — Files analyzed, code written, tests run
3. Footer — Completion status, commit hash, files changed

Logs are published incrementally as the agent works and persist across sessions.