Interactive Shell

Use the FTL interactive shell for multi-turn agent conversations

The FTL interactive shell provides a persistent session where you can issue follow-up instructions to the agent without cold-booting between tasks.

Starting the Shell

Launch the interactive shell from your project directory:

ftl

You must run ftl init in your project before using the interactive shell.

Shell Prompt States

The shell has two prompt states:

Idle

ftl>

No active session. Type a task to start a new session.

Active Session

ftl[active]>

Session is active. Follow-up instructions continue the same agent conversation.

Basic Workflow

1. Start Shell

   ftl
   

   Output:

   FTL Shell
   Agent: claude-code | Tester: claude-haiku-4-5-20251001
   Type a task to start. Commands: test, diff, merge, reject, list, restore <id>, exit
   
   ftl>
   
2. Issue Task

   Type a task description to start a new session:

   ftl> build a login page with email and password
   

   FTL snapshots your project, boots the sandbox, and runs the agent.

3. Review Changes

   Once the agent completes, the session becomes active:

   Session active. Commands: test, diff, merge, reject
   Or type a follow-up instruction for the agent.
   
   ftl[active]>
   
4. Follow-up Instructions

   Continue the conversation with follow-up tasks:

   ftl[active]> add form validation
   

   The agent continues in the same container with full context.

5. Merge or Reject

   When satisfied, merge the changes:

   ftl[active]> merge
   

   Or reject to discard all changes:

   ftl[active]> reject
   

Session Commands

These commands are available when a session is active:

diff

Show all changes since the snapshot:

ftl[active]> diff

Displays a unified diff of all modified files.

test

Re-run tests manually:

ftl[active]> test

Executes the adversarial tests generated for this session.

merge

Review and merge changes to your project:

ftl[active]> merge

FTL displays the diff and prompts for approval:

Interactive Review

ftl[active]> merge

[Diff displayed]

Approve changes?
  a — approve and merge
  r — reject and discard
  Any other input — ask the model a question

>

reject

Discard all changes and end the session:

ftl[active]> reject

The sandbox state is discarded and the prompt returns to ftl>.

Snapshot Commands

These commands are available at any time:

list

List snapshots for the current project:

ftl> list

Output:

  abc123  /home/user/myproject
  def456  /home/user/myproject
  ghi789  /home/user/myproject

list all

List snapshots for all projects:

ftl> list all

restore

Restore a previous snapshot:

ftl> restore abc123

FTL prompts for confirmation before restoring:

Restore snapshot abc123?
Are you sure? (y/n) >

Example Session

Here’s a complete interactive session:

$ ftl
FTL Shell
Agent: claude-code | Tester: claude-haiku-4-5-20251001

ftl> create a Stripe payment module

[Snapshotting...]
[Booting sandbox...]
[Running agent...]
[Agent completes]

Session active. Commands: test, diff, merge, reject

ftl[active]> add error handling for failed payments

[Agent continues...]
[Agent completes]

ftl[active]> diff

[Unified diff displayed]

ftl[active]> test

[Tests run]
All tests passed.

ftl[active]> merge

[Diff displayed]

Approve changes?
  a — approve and merge
  r — reject and discard
  Any other input — ask the model a question

> does this handle webhook signature verification?

Yes, the implementation includes webhook signature verification using
Stripe's constructEvent() method with the webhook secret...

Approve changes?
> a

Changes merged to project.

ftl> exit
Goodbye.

Session Lifecycle

Persistent Container

The shell uses a persistent container per project:

Location	Behavior	Notes
/workspace/	Wiped and restored from snapshot on each task	Project files
/home/ftl/.local/	Persists across tasks	pip install packages
/home/ftl/.claude/	Persists across tasks	Conversation history
Global node_modules	Persists across tasks	npm install -g

Follow-up Context

When you issue a follow-up instruction:

1. Same Container

   The agent runs in the same container with all previous context

2. Same Conversation

   Conversation history in /home/ftl/.claude/ is preserved

3. No Snapshot

   FTL does not create a new snapshot for follow-ups

4. Cumulative Diff

   The diff shows all changes since the original snapshot

Exiting the Shell

Exit the shell with any of these:

exit command

ftl> exit
Goodbye.

If you exit with an active session, FTL automatically rejects all changes to prevent accidental merges.

Shell Implementation

The shell is implemented in ftl/cli.py:

ftl/cli.py

def shell():
    """Interactive FTL shell with session support."""
    console = Console()

    if not find_config():
        console.print("[red]No .ftlconfig found. Run 'ftl init' first.[/red]")
        raise SystemExit(1)

    config = load_config()
    console.print("[bold]FTL Shell[/bold]")
    console.print(f"[dim]Agent: {config['agent']} | Tester: {config['tester']}[/dim]")
    console.print("[dim]Type a task to start. Commands: test, diff, merge, reject, list, restore <id>, exit[/dim]\n")

    from ftl.snapshot import create_snapshot_store
    snapshot_store = create_snapshot_store(config)
    session = None

    while True:
        prompt = "ftl[active]> " if session and session.is_active else "ftl> "
        try:
            user_input = input(prompt).strip()
        except (KeyboardInterrupt, EOFError):
            console.print("\n[dim]Goodbye.[/dim]")
            if session and session.is_active:
                session.reject()
            break

        if not user_input:
            continue

        if user_input in ("exit", "quit"):
            if session and session.is_active:
                session.reject()
            break

        # [Command handling logic]

Tips

Use follow-ups for refinement

Instead of crafting perfect initial instructions, start with a basic task and refine with follow-ups:

ftl> create a login form
ftl[active]> add client-side validation
ftl[active]> add password strength indicator
ftl[active]> add remember me checkbox

Check diffs before merging

Always run diff before merge to review all accumulated changes:

ftl[active]> diff
ftl[active]> merge

Use list to track snapshots

Run list to see all snapshots for the current project:

ftl> list

Use restore <id> if you need to revert to a previous state.

Test early and often

Run tests manually after each follow-up to catch issues early:

ftl[active]> add error handling
ftl[active]> test