Skip to main content
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