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

# ACP Integration

> Integrate Terramind with Zed and other editors via ACP

## Zed Editor Integration

Zed has native support for the Agent Client Protocol. Here's how to set up Terramind with Zed.

### Prerequisites

1. Install Terramind:

```bash theme={null}
npm install -g terramind
```

2. Verify installation:

```bash theme={null}
terramind --version
```

### Configuration

Add Terramind to your Zed configuration file:

**Location:** `~/.config/zed/settings.json`

```json theme={null}
{
  "agent_servers": {
    "Terramind": {
      "command": "terramind",
      "args": ["acp"]
    }
  }
}
```

### Using Terramind in Zed

1. **Open your project** in Zed
2. **Open the AI assistant** panel
3. **Select Terramind** from the agent list
4. **Start coding** with AI assistance!

### Custom Working Directory

To specify a working directory:

```json theme={null}
{
  "agent_servers": {
    "Terramind": {
      "command": "terramind",
      "args": ["acp", "--cwd", "/path/to/your/project"]
    }
  }
}
```

### Multiple Projects

Set up different Terramind instances for different projects:

```json theme={null}
{
  "agent_servers": {
    "Terramind-Project1": {
      "command": "terramind",
      "args": ["acp", "--cwd", "/path/to/project1"]
    },
    "Terramind-Project2": {
      "command": "terramind",
      "args": ["acp", "--cwd", "/path/to/project2"]
    }
  }
}
```

***

## Manual Testing

Test the ACP server manually before editor integration:

### Start the Server

```bash theme={null}
terramind acp
```

The server communicates via stdio (standard input/output).

### Send Test Request

Initialize the protocol:

```bash theme={null}
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}' | terramind acp
```

Expected response:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": 1,
    "agentCapabilities": {
      "supportsStreaming": false,
      "supportsTools": true
    }
  }
}
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Server not starting">
    **Symptoms:** Terramind ACP server fails to start in editor

    **Solutions:**

    1. Verify Terramind is installed: `which terramind`
    2. Check the command works in terminal: `terramind acp`
    3. Review editor logs for error messages
    4. Ensure correct path in configuration
  </Accordion>

  <Accordion title="No response from Terramind">
    **Symptoms:** Prompts sent but no response received

    **Solutions:**

    1. Check API key is configured: `terramind auth`
    2. Verify network connectivity
    3. Check for error messages in terminal
    4. Try with `--debug` flag: `terramind acp --debug`
  </Accordion>

  <Accordion title="File access denied">
    **Symptoms:** Terramind can't read/write files

    **Solutions:**

    1. Check file permissions in your project
    2. Verify working directory is correct
    3. Ensure `.gitignore` isn't blocking necessary files
    4. Check editor has file system access
  </Accordion>

  <Accordion title="Wrong project context">
    **Symptoms:** Terramind accessing wrong files

    **Solutions:**

    1. Verify `--cwd` argument is correct
    2. Check you're in the right workspace
    3. Restart the editor/server
    4. Clear any cached state
  </Accordion>
</AccordionGroup>

***

## Advanced Configuration

### Environment Variables

Set environment variables for the ACP server:

```json theme={null}
{
  "agent_servers": {
    "Terramind": {
      "command": "terramind",
      "args": ["acp"],
      "env": {
        "TERRAMIND_MODEL": "claude-sonnet-4-5",
        "TERRAMIND_LOG_LEVEL": "debug"
      }
    }
  }
}
```

### Custom Port (Future)

For network-based communication (when supported):

```json theme={null}
{
  "agent_servers": {
    "Terramind": {
      "command": "terramind",
      "args": ["acp", "--port", "8080"]
    }
  }
}
```

### MCP Server Configuration

Configure MCP servers for extended capabilities:

First, add MCP servers to your Terramind config:

```bash theme={null}
terramind mcp add --name filesystem --command "npx -y @modelcontextprotocol/server-filesystem /path/to/dir"
```

Then use in editor as normal - Terramind will automatically use configured MCP servers.

***

## Editor-Specific Features

### Zed Features

When using Terramind in Zed:

* **Inline suggestions** as you type
* **Quick actions** on selected code
* **Chat interface** for conversations
* **File context** automatically included
* **Multi-file editing** support

### Keybindings

Set up custom keybindings in Zed for quick access:

```json theme={null}
{
  "bindings": {
    "cmd-k": "ai_assistant::toggle",
    "cmd-shift-k": "ai_assistant::new_conversation"
  }
}
```

***

## Best Practices

### Prompt Engineering

Get better results with clear prompts:

**Good:**

```
"Refactor the handleSubmit function in Form.tsx to use async/await and add proper error handling"
```

**Better:**

```
"In Form.tsx, refactor handleSubmit to:
1. Use async/await instead of .then()
2. Add try/catch for error handling
3. Show user-friendly error messages
4. Follow our project's error handling pattern from utils/errors.ts"
```

### Context Management

Help Terramind understand your intent:

* **Mention specific files** when relevant
* **Describe the desired outcome** clearly
* **Reference related code** that should be considered
* **Specify patterns** to follow

### Iterative Development

Work iteratively with Terramind:

1. **Start broad**: "Create a user profile component"
2. **Refine**: "Add form validation"
3. **Enhance**: "Add loading states and error handling"
4. **Polish**: "Add accessibility attributes"

***

## Performance Tips

### Optimize Response Time

* **Be specific** to reduce unnecessary analysis
* **Limit context** to relevant files only
* **Use focused prompts** for quick tasks
* **Choose appropriate models** (Haiku for speed)

### Reduce Token Usage

* **Clear old conversations** when switching topics
* **Reference files by name** instead of pasting content
* **Use concise language** in prompts
* **Avoid redundant context**

***

## Security Considerations

### File Access

Terramind requests permission before:

* Writing or modifying files
* Executing bash commands
* Accessing sensitive files

Review permissions carefully!

### API Keys

* **Never commit** API keys to repositories
* **Use environment variables** for sensitive data
* **Rotate keys** periodically
* **Restrict permissions** to minimum necessary

### Code Review

Always review AI-generated code:

* **Check for security issues**
* **Verify logic correctness**
* **Test thoroughly**
* **Follow team standards**

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture Details" icon="diagram-project" href="/acp/architecture">
    Learn how ACP works under the hood
  </Card>

  <Card title="CLI Usage" icon="terminal" href="/cli/overview">
    Use Terramind from the command line
  </Card>
</CardGroup>