Skip to main content
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:
PartSourceExample
Dynamic infoAutomaticCurrent date, workspace name, active user
Generated contextGuild systemsConnected GitHub repositories
Manual contextYouProject 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:
FieldRequiredNotes
workspace_idyesPath parameter
statusyes"DRAFT" or "PUBLISHED"
contextyesThe manual context text (typically Markdown)
summarynoShort 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`