Workspaces & Resuming

Shannon uses workspaces to store scan state, logs, prompts, and deliverables. Workspaces allow interrupted or failed runs to resume without re-running completed agents.

How workspaces work

• Every run creates a workspace.
• Auto-named workspaces use the target hostname and a session ID, such as example-com_shannon-1771007534808.
• npx mode stores workspaces in ~/.shannon/workspaces/.
• Source-build mode stores workspaces in ./workspaces/.
• Use -w <name> to give a run a custom name.
• To resume a run, pass the same workspace name with -w.
• Each agent’s progress is checkpointed so resumed runs can skip completed work.
• The final report is surfaced at the workspace root as Security-Assessment-Report.md. Run internals (deliverables, logs, prompts, and session state) live under a hidden .shannon/ directory.

Note

The URL must match the original workspace URL when resuming. Shannon rejects mismatched URLs to prevent cross-target contamination.

Examples

npx (recommended)

Start with a named workspace:

npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w my-audit

Resume the same workspace (same command, same -w name):

npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w my-audit

Resume an auto-named workspace:

npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w example-com_shannon-1771007534808

List all workspaces:

npx @keygraph/shannon workspaces

Build from source

Start with a named workspace:

./shannon start -u https://example.com -r /path/to/repo -w my-audit

Resume the same workspace (same command, same -w name):

./shannon start -u https://example.com -r /path/to/repo -w my-audit

Resume an auto-named workspace:

./shannon start -u https://example.com -r /path/to/repo -w example-com_shannon-1771007534808

List all workspaces:

./shannon workspaces

Workspace contents

Each workspace directory holds the full record of a run. The top level holds only the final report; everything else is nested under a hidden .shannon/ directory:

workspaces/{hostname}_{sessionId}/
|-- Security-Assessment-Report.md   # the final report (the deliverable)
`-- .shannon/                       # internals
    |-- deliverables/               # report source, per-phase analysis, queues
    |-- agents/                     # per-agent logs
    |-- prompts/                    # rendered prompts
    |-- scratchpad/                 # screenshots, scripts
    |-- session.json                # resume state
    `-- workflow.log