Workspace Context Linking (curd context)

One of the most powerful features of CURD is the Context Registry. It allows you to dynamically mount external directories or repositories into your current workspace, giving AI agents and the CURD CLI immediate, high-fidelity awareness of code that exists entirely outside of your project folder.

Why Context Linking?

In real-world engineering, you are rarely working on an isolated repository.

• You might be building a frontend that relies on a backend repository.
• You might be using a sprawling monorepo where you only want to focus on two microservices.
• You might want to give an AI agent access to a local clone of a third-party open-source library so it can read the actual source code instead of hallunicating the API.

CURD solves this by allowing you to link these external paths via aliases (e.g., @backend, @react-source). The GraphEngine and SearchEngine seamlessly extend their reach into these paths.

Adding a Context

Use the curd context add command to link an external path:

# Link a backend repository with an alias
curd context add ../backend-service --alias @backend
 
# Link local React source code purely for indexing and graph lookup
curd context add ~/open-source/react --alias @react --index
 
# Link a shared library with read permissions
curd context add ../shared-lib --alias @shared --read

Context Modes

When you link a context, you can restrict exactly what operations the CURD engines (and by extension, the AI agents) are allowed to perform on that external path.

1. --index (Index-Only Mode)

   • Allowed: Search and Graph querying.
   • Denied: Reading the actual file text or modifying the files.
   • Use Case: You want the AI to know that an external struct or function exists, but you don’t want to waste context-window tokens letting it read massive library files.

2. --read (Read Mode)

   • Allowed: Search, Graph, and read tool calls.
   • Denied: Modifications (edit, refactor).
   • Use Case: Best for open-source library clones or third-party reference documentation where the AI needs to read the source code but shouldn’t accidentally edit it.

3. Default (Write Mode)

   • Allowed: Full access (Search, Graph, Read, Edit).
   • Denied: Running shell commands in the external path (shell is strictly workspace-bound).
   • Use Case: Standard microservice or monorepo development where the agent needs to patch both repositories simultaneously in one atomic transaction.

How it works for AI Agents

Once a context is registered in .curd/contexts.json, the path aliases are automatically exposed to the AI model through the MCP server.

If the agent needs to search for an API handler in the backend, it simply calls:

{
  "name": "search",
  "arguments": {
    "query": "login_handler",
    "directory": "@backend"
  }
}

If it needs to edit a shared type:

{
  "name": "edit",
  "arguments": {
    "uri": "@shared/src/types.rs::User",
    "code": "..."
  }
}

By keeping the context mounting at the backend layer, the prompt remains clean, the security boundaries remain intact, and the AI agent gets a massive boost in cross-repository intelligence.

Managing Contexts

You can manage your existing context mounts natively:

# List all active contexts
curd context list
 
# Remove a specific context
curd context remove @backend