agents2agentsai/workspace

Workspace Management

Workspaces organize multi-repo work, execution runs, and research resources under ~/.ata/workspaces/<id>/. Each workspace has a JSON manifest (workspace.json) tracking repos, runs, papers, datasets, artifacts, indexes, snapshots, and links.

Prerequisites

Required: git. The ata binary is already in PATH.

Containment Rules

• ALWAYS use ata workspace resolve '@spec' for workspace paths — never construct paths manually
• ALWAYS use ata workspace check-host <url> before any clone operation
• ALWAYS use typed mutation commands (e.g. repo-pin, add-entry, set-field) for manifest changes (atomic lock + version bump)
• ALWAYS resolve the target workspace ID first (store as WID) and pass --workspace "$WID" on every mutating ata workspace command
• NEVER run mutating workspace commands without explicit --workspace "$WID" (even if resolution would normally infer one)
• ALWAYS run ata workspace select "$WID" directly when asked to switch workspaces
• If you are unsure which workspace subcommand fits the user's intent, run ata workspace search-commands "<intent>" first. It prints a simplified manual for the best-matching command and hides shared scoping noise.
• Do not use ata workspace search-commands when the workflow is already explicit. For "create a new workspace and clone repos", go straight to ata workspace init, ata workspace select, then ata workspace repo-clone ... --workspace "$WID".
• NEVER preflight with ata --help or ata workspace --help; only probe help after an actual "unknown subcommand" failure
• ALWAYS audit significant operations via ata workspace audit
• For repo cloning, prefer the thick command ata workspace repo-clone <url> <alias> which enforces all of the above

Command Reference

| Command | Description | |---------|-------------| | ata workspace search-commands "<intent>" | Print a simplified manual for the best-matching workspace command | | ata workspace init <name> | Create workspace, print ID | | ata workspace list | List workspaces as JSON | | ata workspace read [--workspace ID] | Print manifest JSON | | ata workspace select <id> | Set active workspace (session-aware) | | ata workspace delete <id> | Remove workspace tree | | ata workspace resolve '<@spec>' [--workspace ID] | Resolve @-path to absolute path | | ata workspace check-host <url> [--workspace ID] | Validate URL + host allowlist | | ata workspace audit '<json>' [--workspace ID] | Append audit entry | | ata workspace audit-query [--workspace ID] [--since TS] [--until TS] [--ops OPS] [--limit N] | Query audit log | | ata workspace run-locked --level <lvl> [--target-id ID] -- <cmd> | Run under fine-grained lock | | ata workspace mirror-path <url> | Print shared mirror cache path | | ata workspace repo-clone <url> <alias> [--workspace ID] [--full] | Full repo_add: validate + clone + register + audit | | ata workspace run-setup <name> --source-alias <alias> [--strategy S] [--workspace ID] | Full run creation: dirs + materialize + register + audit | | ata workspace repo-update-state --alias X --head-sha Y [--head-ref Z] [--workspace ID] | Update repo HEAD state | | ata workspace repo-pin --alias X --sha Y [--workspace ID] | Pin repo to SHA | | ata workspace repo-unpin --alias X [--workspace ID] | Unpin repo (tracking mode) | | ata workspace repo-remove --alias X [--workspace ID] | Remove repo dir + manifest entry + audit | | ata workspace run-update-status --id X --status Y [--workspace ID] | Update run status | | ata workspace run-remove --id X [--workspace ID] | Remove run + worktree cleanup + audit | | ata workspace add-entry --collection <type> --json '{...}' [--workspace ID] | Append to collection (papers/datasets/artifacts/links/snapshots/indexes) | | ata workspace remove-entry --collection <type> --id X [--workspace ID] | Remove by ID from collection | | ata workspace set-field --path <dotted.path> --value '<json>' [--workspace ID] | Set manifest field at dotted path | | ata workspace index-update-status --id X --status Y [--workspace ID] | Update index status | | ata workspace materialize <spec-path> [--workspace ID] [--dry-run] | Materialize workspace from a spec file | | ata workspace export-spec [--workspace ID] [--output PATH] | Export workspace repos as a portable spec file | | ata workspace diff-spec <spec-path> [--workspace ID] | Show what materialize would do (add/pin/skip) | | ata workspace recipe <operation> | Print step-by-step recipe for an operation | | ata workspace recipe list | List all available recipes |

Workspace resolution: --workspace > project pin (.codex/workspace.json) > session > global.

Path Aliases

| Alias | Resolves to | |-------|------------| | @<alias>/path | repos/<alias>/path | | @run/<id>/path | runs/<id>/path | | @kb/path | knowledge-base/path | | @notes/path | notes/workspace/path | | @notes/<category>/path | notes/<category>/path | | @artifacts/<id>/path | artifacts/<id>/path | | @cache/path | cache/path | | @index/<id>/path | indexes/<id>/path | | @ws/<other_id>/path | Cross-workspace path |

Reserved aliases: run, notes, ws, artifacts, kb, index, cache.

Directory Layout

~/.ata/workspaces/<id>/
  workspace.json          # Manifest (schema v2, camelCase)
  repos/<alias>/          # Cloned repositories
  runs/<run-id>/          # Execution runs (run.json, root/, logs/)
  artifacts/              # Materialized artifacts
  indexes/                # Search indexes
  cache/                  # Workspace cache
  locks/workspace.lock    # Exclusive flock (30s timeout)
  knowledge-base/         # cards/, topics/, briefings/, explanations/
  notes/                  # workspace/, repos/, papers/, datasets/, runs/
    workspace/audit.ndjson

Detailed Instructions

For detailed step-by-step instructions on specific operations, read the appropriate reference file:

| Category | File | Covers | |----------|------|--------| | Workspace lifecycle | <skill_dir>/scripts/references/workspace-management.md | init, list, select, delete, resolution | | Repository ops | <skill_dir>/scripts/references/repo-management.md | repo-clone, update, pin, remove, mirrors | | Execution runs | <skill_dir>/scripts/references/run-management.md | run-setup, exec, list, delete, GC | | Research resources | <skill_dir>/scripts/references/resources.md | papers, datasets, artifacts, links | | Snapshots & export | <skill_dir>/scripts/references/snapshots-and-export.md | snapshot, restore, export, import | | Audit & KB | <skill_dir>/scripts/references/audit-and-kb.md | audit, audit-query, KB, locking | | Python environments | <skill_dir>/scripts/references/python-env-manager.md | detect, create, select, multi-env workflows | | Remote sync | <skill_dir>/scripts/references/remote-sync.md | push/pull source, divergence detection, sync strategies |

Alternatively, use ata workspace recipe <operation> for quick inline recipes.