Workspace context

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.

# 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:

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.

# 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. Include guildTools in your agent so task.guild is available.

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.

Read the context history

"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

"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".

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.

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:

# 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`

Overview

The Smith

Platform

Insights

Agent SDK

Workspace context

What agents see

Edit context

Web UI

CLI

Versions

Programmatic access

Read the context history

Publish a new version

Writing good context

​What agents see

​Edit context

​Web UI

​CLI

​Versions

​Programmatic access

​Read the context history

​Publish a new version

​Writing good context

What agents see

Edit context

Web UI

CLI

Versions

Programmatic access

Read the context history

Publish a new version

Writing good context