Shared Agent Sessions

Named sessions let you share a filesystem between multiple agents, terminals, or runs. All participants see the same copy-on-write view of your project.

Creating a Session

Use --session to create a named session:

agentfs run --session my-project /bin/bash

This creates a session called my-project. All changes are stored in .agentfs/my-project.db.

Resuming a Session

Run the same command to resume where you left off:

# First run - make some changes
agentfs run --session my-project /bin/bash
$ echo "hello" > test.txt
$ exit

# Second run - changes are still there
agentfs run --session my-project /bin/bash
$ cat test.txt
hello

Multi-Terminal Collaboration

Multiple terminals can share the same session simultaneously:

# Terminal 1
agentfs run --session shared-work /bin/bash

# Terminal 2 - joins the same filesystem
agentfs run --session shared-work python3 agent.py

# Terminal 3 - also sees the same files
agentfs run --session shared-work vim

All terminals share the same copy-on-write filesystem. Changes made in one terminal are immediately visible in others.

Use Cases

Iterative Development

Work on a task across multiple sessions:

# Morning session
agentfs run --session feature-x /bin/bash
# ... work on the feature, then exit for lunch

# Afternoon session - continue where you left off
agentfs run --session feature-x /bin/bash

Safe Experimentation

Create a session, try something risky, then decide whether to keep it:

agentfs run --session experiment /bin/bash
# ... try some changes

# Option A: Happy with changes
agentfs diff experiment  # Review
# Apply changes to real filesystem (manually or via script)

# Option B: Discard everything
rm .agentfs/experiment.db

Agent Supervision

Run an agent and monitor its work from another terminal:

# Terminal 1: Run the agent
agentfs run --session agent-task python3 agent.py

# Terminal 2: Watch what it's doing
agentfs run --session agent-task /bin/bash
$ watch ls -la  # See files being created
$ tail -f agent.log  # Monitor logs

Managing Sessions

List files in a session:

agentfs fs ls my-session

View session changes:

agentfs diff my-session

Delete a session:

rm .agentfs/my-session.db

Session Storage

Sessions are stored as SQLite databases in .agentfs/:

.agentfs/
├── my-project.db
├── experiment.db
└── shared-work.db

Each database contains:

All modified files
Deleted file markers (whiteouts)
Tool call audit log
Key-value store data

Next Steps

Auditing

Inspect what happened in a session

Overlay Filesystem

How copy-on-write works

​Creating a Session

​Resuming a Session

​Multi-Terminal Collaboration

​Use Cases

​Iterative Development

​Safe Experimentation

​Agent Supervision

​Managing Sessions

​Session Storage

​Next Steps