> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace context

> Give agents background knowledge about your workspace.

Workspace context is a text document that Guild passes to every agent when it runs in your workspace. Use it to tell agents about your project, team conventions, preferred tools, and anything else they need to do their job well.

## What agents see

When an agent runs, it receives a compiled context made up of three parts:

| Part              | Source        | Example                                          |
| ----------------- | ------------- | ------------------------------------------------ |
| Dynamic info      | Automatic     | Current date, workspace name, active user        |
| Generated context | Guild systems | Connected GitHub repositories                    |
| Manual context    | You           | Project overview, coding conventions, team notes |

The manual context is the part you write and maintain.

## Edit context

### Web UI

Open your workspace and click **Context** in the left sidebar. The editor lets you write in Markdown. Changes are saved as a draft until you publish them.

### CLI

The `guild workspace context edit` command opens your `$EDITOR` with the current published context. When you save and exit, a draft is created automatically.

```bash theme={null}
# Edit the current context
guild workspace context edit <workspace-id>

# Edit from a specific version
guild workspace context edit <workspace-id> --from <context-id>
```

After editing, publish the draft to make it active:

```bash theme={null}
guild workspace context publish <workspace-id> <context-id>
```

## Versions

Every change creates a new version. Versions are either `DRAFT` or `PUBLISHED` — only the latest published version is used when agents run.

```bash theme={null}
# List all versions
guild workspace context list <workspace-id>

# Inspect a version
guild workspace context get <workspace-id> <context-id>
```

## Programmatic access

Agents can read the workspace context history and append new versions through the [Guild service](/sdk/task-object#taskguild--platform-operations). Include `guildTools` in your agent so `task.guild` is available.

<Note>
  Workspace contexts are **append-only versioned snapshots**. There is no update or delete API — every call to `create_workspace_context` produces a brand-new row. To "edit" the published context, fetch the latest version, merge in your changes, and create a new `PUBLISHED` version.
</Note>

### Read the context history

```typescript theme={null}
"use agent"

import { agent, guildTools, type Task } from "@guildai/agents-sdk"
import { z } from "zod"

const tools = { ...guildTools }
type Tools = typeof tools

const inputSchema = z.object({ workspace_id: z.string() })
const outputSchema = z.object({
  count: z.number(),
  latest_status: z.string().nullable(),
})

async function run(
  input: z.infer<typeof inputSchema>,
  task: Task<Tools>,
): Promise<z.infer<typeof outputSchema>> {
  const { items } = await task.guild!.get_workspace_contexts({
    workspace_id: input.workspace_id,
    limit: 10,
  })
  const latest = items[0]
  return {
    count: items.length,
    latest_status: latest?.status ?? null,
  }
}

export default agent({
  description: "Summarizes the workspace context history.",
  inputSchema,
  outputSchema,
  tools,
  run,
})
```

`get_workspace_contexts` returns `{ items, pagination }`, with `items` ordered newest-first. Each `Context` has `id`, `status` (`"DRAFT"` or `"PUBLISHED"`), `manual_context`, `generated_context`, `summary`, `created_at`, `updated_at`, and `author` fields.

### Publish a new version

```typescript theme={null}
"use agent"

import { agent, guildTools, type Task } from "@guildai/agents-sdk"
import { z } from "zod"

const tools = { ...guildTools }
type Tools = typeof tools

const inputSchema = z.object({
  workspace_id: z.string(),
  addition: z.string().describe("New text to append to the context"),
})
const outputSchema = z.object({ context_id: z.string() })

async function run(
  input: z.infer<typeof inputSchema>,
  task: Task<Tools>,
): Promise<z.infer<typeof outputSchema>> {
  // Fetch the latest published context so we can append to it.
  const { items } = await task.guild!.get_workspace_contexts({
    workspace_id: input.workspace_id,
    limit: 10,
  })
  const latestPublished = items.find((c) => c.status === "PUBLISHED")
  const base = latestPublished?.manual_context ?? ""
  const merged = base ? `${base}\n\n${input.addition}` : input.addition

  const created = await task.guild!.create_workspace_context({
    workspace_id: input.workspace_id,
    status: "PUBLISHED",
    context: merged,
    // summary is optional — Guild auto-generates one if omitted.
  })

  return { context_id: created.id }
}

export default agent({
  description: "Appends a note to the workspace context.",
  inputSchema,
  outputSchema,
  tools,
  run,
})
```

**Parameters for `create_workspace_context`:**

| Field          | Required | Notes                                        |
| -------------- | -------- | -------------------------------------------- |
| `workspace_id` | yes      | Path parameter                               |
| `status`       | yes      | `"DRAFT"` or `"PUBLISHED"`                   |
| `context`      | yes      | The manual context text (typically Markdown) |
| `summary`      | no       | Short description; auto-generated if omitted |

Only the **latest `PUBLISHED` row** is used when agents run. Drafts are persisted but inert until you publish them by creating a new row with `status: "PUBLISHED"`.

<Tip>
  For `llmAgent`, the same endpoints are available as the `guild_get_workspace_contexts` and `guild_create_workspace_context` tools — the LLM can call them directly when `guildTools` is included.
</Tip>

## Writing good context

Context is injected verbatim into the agent's prompt, so write it as if you're briefing a capable new team member.

**Include:**

* What the project does and its tech stack
* Repository structure and important directories
* Coding conventions and style preferences
* Tools and services the team uses
* Links to relevant internal resources

**Keep it focused.** Long or noisy context degrades agent performance. Aim for what's genuinely useful for most tasks in this workspace — not an exhaustive wiki.

**Example:**

```markdown theme={null}
# Acme Platform

A B2B SaaS platform for inventory management. The backend is Python (FastAPI)
and the frontend is React + TypeScript. PostgreSQL is the primary database.

## Repositories

- `acme/api` — FastAPI backend
- `acme/app` — React frontend
- `acme/infra` — Terraform infrastructure

## Conventions

- Python: follow PEP 8, use type hints everywhere, prefer `ruff` for linting
- TypeScript: strict mode, functional components, no `any` types
- Git: conventional commits (`feat:`, `fix:`, `chore:`)
- PRs require at least one review before merging to `main`
```