# Workspace context

Workspace context gives an Agent a named file tree and optional Sources. The Workspace decides what exists; Capabilities and the selected Driver decide how the Agent can access it.

Use the [Workspace preset](https://vitehub.dev/docs/agents/workspace-preset) for a read-only Codex Agent with Source citation instructions.

Use a Workspace for project files, documentation, generated state, Source-backed paths, and controlled writeback. Do not use it as hidden prompt storage; model-facing policy belongs in [Instructions](https://vitehub.dev/docs/agents/instructions).

## Add a read-only Workspace

Enable both integrations in the ViteHub preset.

```ts [vite.config.ts]
import { defineConfig } from 'vite'
import { vitehub } from 'vite-hub'

export default defineConfig({
  plugins: [
    vitehub({ preset: 'node', agent: true, workspace: true }),
  ],
})
```

Declare a Source and grant a model-backed Driver read-only shell access:

```ts [server/agents/docs/agent.ts]
import { defineAgent } from 'vite-hub/agent'
import { workspaceShell } from 'vite-hub/agent/capabilities'
import { glob } from 'vite-hub/workspace'

export default defineAgent({
  driver: {
    model: 'openai/gpt-5.1-mini',
    instructions: [
      'Answer from the docs Source.',
      'Use Workspace inspection before answering. Say when evidence is missing.',
    ],
  },
  capabilities: [workspaceShell({ mode: 'read' })],
  workspace: {
    sourceRootDir: process.cwd(),
    sources: {
      docs: glob({ cwd: '.', include: ['docs/content/**/*.md'] }),
    },
  },
})
```

The Source makes files available under the Workspace. `workspaceShell({ mode: 'read' })` exposes read operations to the model. Without that Capability, declaring a Source alone does not grant model-facing file access.

## Reuse a Workspace

Use `defineWorkspace()` when several Agents share the same file tree or Source configuration.

```ts [server/workspaces/product-docs.ts]
import { defineWorkspace, glob } from 'vite-hub/workspace'

export default defineWorkspace({
  sourceRootDir: process.cwd(),
  sources: {
    docs: glob({ cwd: '.', include: ['docs/content/**/*.md'] }),
  },
})
```

```ts [server/agents/support.ts]
import { defineAgent } from 'vite-hub/agent'
import { workspaceShell } from 'vite-hub/agent/capabilities'

export default defineAgent({
  driver: { model: 'openai/gpt-5.1-mini' },
  capabilities: [workspaceShell({ mode: 'read' })],
  workspace: 'product-docs',
})
```

## Scope access by Actor

Use `access()` when trusted caller identity narrows the files visible to one invocation. Place it before `workspaceShell()` so the shell receives the scoped Workspace.

```ts [server/agents/editor.ts]
import { defineAgent } from 'vite-hub/agent'
import { access, workspaceShell } from 'vite-hub/agent/capabilities'

export default defineAgent({
  capabilities: [
    access({
      workspace: {
        defaultScope: 'support',
        scopes: {
          support: { paths: ['support'] },
        },
      },
    }),
    workspaceShell({ mode: 'read' }),
  ],
  driver: { model: 'openai/gpt-5.1-mini' },
  workspace: 'product-docs',
})
```

Authenticate the request and pass an [Agent Actor](https://vitehub.dev/docs/agents/actors) before deriving Actor-specific access. Workspace policy enforces authorization, so base it only on trusted identity and application-owned facts. Actor-scoped Workspace access from `access()` is read-only for model-backed and custom Drivers; provider Drivers receive a writable session limited to the selected paths. Without Actor-scoped Access, write authority depends on the Workspace mode, its rules, and the tools exposed to the Driver.

## Use Workspace context with a provider

Provider Drivers receive the rendered instruction document and selected Workspace files in a temporary local working directory. Successful write-mode invocations commit through Workspace rules.

```ts [server/agents/review/agent.ts]
import { defineAgent } from 'vite-hub/agent'

export default defineAgent({
  driver: { kind: 'codex', model: 'gpt-5.5' },
  workspace: { mode: 'write' },
})
```

## Preserve GitHub PR history

A Node process host can use `createGitHubHost()` from `@vite-hub/agent/server/github` to prepare an exact PR head with Git. Supply `repository`, `number`, `headSha`, `headRepository`, and `headRef` to `withPullRequestCheckout()`. The host fetches the source branch directly and rejects a changed head. Each pass uses a fresh temporary checkout. The host removes its contents when the callback finishes, including after failure, cancellation, or timeout. Cleanup is best effort and preserves the callback result or error if filesystem discovery or deletion fails. Cleanup retains an empty temporary directory to preserve concurrent pathname replacements.

When a provider materializes a separate directory, call the checkout callback's `prepareWorkspace(cwd)` in the provider launch hook. It restores independent Git history and removes saved authentication configuration. Set Workspace `commit: false` if the host will push the provider's commits instead of copying files back through Workspace writeback. When `commit: false` leaves no Workspace or Capability rule with `commit`, the invocation also skips the whole-tree Workspace diff after the run.

After the provider finishes, the host can call `checkout.push(cwd)`. This refreshes source credentials, verifies ancestry, and rejects a source branch that changed after preparation. Do not give the provider the host's GitHub credentials when pushes require host approval. Checkout preparation applies only to GitHub PR workspaces and requires Git, not the GitHub CLI.

## Keep context explicit

| Need | Use |
| --- | --- |
| Files or generated state | Workspace files and Sources |
| Model-facing rules | Colocated or Driver Instructions |
| Read or write tools | Capabilities such as `workspaceShell` |
| Caller-specific file scope | Access plus a trusted Agent Actor |
| Provider working directory | A write-mode Workspace |

Inspect the resolved Workspace, Sources, and access policy through the [CLI](https://vitehub.dev/docs/development/cli) before relying on them in production.