Workspace View

Browse and edit agent workspace files, manage git history from the web dashboard

The Workspace view lets you browse, edit, and manage an agent’s workspace files and git history — all from the web console. Each agent has its own workspace under ~/.comis/agents/<agentId>/workspace, and the workspace files (SOUL.md, IDENTITY.md, AGENTS.md, etc.) shape that agent’s personality and behavior; see Identity for the concept.

Who it’s for: authors editing an agent’s persona without leaving the dashboard, and operators who need a quick rollback after a bad change.

Route

• /agents/:id/workspace — opens the workspace manager for the named agent. You arrive here by clicking Workspace on the agent detail page.

Backing RPC

• workspace.status(agentId) — overall workspace status (git init state, bootstrap state)
• workspace.init(agentId) — initialize the workspace git repository
• workspace.listDir(agentId, path?) — file tree
• workspace.readFile(agentId, filePath) — file content
• workspace.writeFile(agentId, filePath, content) — save
• workspace.deleteFile(agentId, filePath) — delete
• workspace.resetFile(agentId, filePath) — restore template content
• workspace.git.status(agentId) — branch, changed files
• workspace.git.log(agentId) — recent commit history
• workspace.git.diff(agentId, filePath?) — diff
• workspace.git.commit(agentId, message) — commit
• workspace.git.restore(agentId, filePath) — discard local edits

What You See

The Workspace view has a status bar at the top and two tabs — Files and Git — that organize the workspace into file management and version control.

Status bar at the top of the page shows the workspace directory path (for example, ~/.comis/agents/{agentId}/workspace), a git repo status tag indicating whether a git repository has been initialized, and a bootstrap status tag showing whether the workspace has been bootstrapped with template files.

Tab bar below the status bar lets you switch between the Files tab and the Git tab.

Files Tab

The Files tab is split into two panels.

Left panel — The file tree sidebar lists all workspace files in two sections:

• Template Files — The 9 core workspace files that shape your agent’s personality and behavior: SOUL.md, IDENTITY.md, USER.md, AGENTS.md, ROLE.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md, and BOOT.md. Each file shows a presence dot indicating whether it exists in the workspace.
• Directories — The 6 standard subdirectories for organizing agent content: projects, scripts, documents, media, data, and output.

Right panel — When you select a file, an editor appears with:

• A filename header showing the current file name
• An unsaved-changes indicator (a dot next to the filename) when you have modified content that has not been saved
• A textarea where you edit the file content
• An action bar at the bottom with three buttons: Save (writes your changes), Reset to Default (restores a template file to its original content), and Delete (removes the file)

When you select a directory instead of a file, a table appears showing the directory contents with four columns:

Column	What It Shows
Name	The file or subdirectory name
Type	Whether the entry is a file or directory
Size	The file size in bytes
Modified	When the entry was last changed

Git Tab

The Git tab provides version control for your workspace files. It has four sections:

Status section — Shows the current branch name, the number of changed files, and a list of each changed file. Every file has a status badge indicating its state:

• M — Modified (changed since last commit)
• A — Added (new file staged for commit)
• D — Deleted (removed since last commit)
• ?? — Untracked (new file not yet tracked by git)

Each modified or deleted file has a Restore button that discards your changes and reverts the file to its last committed version.

Diff viewer — Click a changed file to see its diff. The viewer uses color-coded display: additions appear in green, deletions appear in red, and hunk headers appear in cyan.

Commit form — A message input field and a Commit button. Enter a description of your changes and click Commit to create a new git commit.

Recent Commits — A list of previous commits, each showing a 7-character SHA hash, the commit message, and the relative time since the commit was made.

Common Tasks

Editing a Workspace File

1. Navigate to the workspace

   Go to Agents in the sidebar, click the agent you want to edit, then click the Workspace button in the agent detail header.

2. Select a file

   In the file tree on the left, click the file you want to edit. The file content loads in the editor on the right.

3. Make your changes

   Edit the content in the textarea. An unsaved-changes dot appears next to the filename to remind you that changes have not been saved.

4. Save

   Click Save in the action bar. The unsaved-changes indicator disappears once the file is written.

Resetting a File to Default

1. Select a template file

   Click one of the 9 template files in the file tree (SOUL.md, IDENTITY.md, USER.md, AGENTS.md, ROLE.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md, or BOOT.md).

2. Click Reset to Default

   Click Reset to Default in the action bar. A confirmation dialog appears.

3. Confirm

   Confirm the reset. The file content is replaced with the original template content.

Reset to Default only works for the 9 template files. Custom files you create do not have a default to reset to.

Deleting a File

1. Select the file

   Click the file you want to delete in the file tree.

2. Click Delete

   Click Delete in the action bar. A confirmation dialog appears.

3. Confirm deletion

   Confirm in the dialog to permanently remove the file from the workspace.

Template files cannot be deleted. If you want to remove a template file’s content, use Reset to Default instead.

Committing Changes

1. Switch to the Git tab

   Click the Git tab in the tab bar.

2. Review changed files

   Check the status section for a list of all changed files and their status badges. Click any file to view its diff.

3. Enter a commit message

   Type a description of your changes in the commit message input field.

4. Commit

   Click Commit to create a new git commit with all your changes.

Viewing a Diff

1. Open the Git tab

   Click the Git tab in the tab bar.

2. Click a changed file

   In the status section, click any file with a status badge to load its diff in the diff viewer. Additions are shown in green, deletions in red, and hunk headers in cyan.

Restoring a File

1. Open the Git tab

   Click the Git tab in the tab bar.

2. Click Restore

   Next to a modified or deleted file in the status list, click the Restore button to discard your changes and revert the file to its last committed version.

Untracked files (status ??) cannot be restored because no committed version exists to revert to.

Security and Limits

The workspace enforces several safety measures:

• Path traversal protection — Files cannot escape the workspace directory. Any attempt to access paths outside the workspace is blocked.
• 1 MB read limit — Individual file reads are capped at 1 MB.
• 512 KB write limit — Individual file writes are capped at 512 KB.
• 512 KB diff cap — Git diffs are truncated at 512 KB.
• 500-character commit message limit — Commit messages longer than 500 characters are rejected.
• Stale git lock cleanup — Stale .git/index.lock files are automatically cleaned up to prevent git operations from hanging.

Related Pages

Identity

How workspace files shape your agent’s personality.

Agents View

Navigate to the Workspace view from an agent’s detail page.

JSON-RPC Methods

Workspace RPC methods for programmatic access.