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

# Best Practices

> Security recommendations and workflow optimization tips for Calmo Bridge IDE

# Best Practices

This guide covers security recommendations, workflow optimization, and tips for getting the most out of Calmo Bridge IDE's integrated environment.

## Security Recommendations

### Command Approval Strategy

<CardGroup cols={2}>
  <Card title="Review Before Approving" icon="eye">
    Always read the full command in the Command Approval panel before clicking **Allow**. Understand what it will do before execution.
  </Card>

  <Card title="Understand Risk Levels" icon="gauge">
    Pay attention to risk indicators:

    * 🟢 LOW = Safe reads
    * 🟡 MEDIUM = State changes
    * 🔴 HIGH = Potentially dangerous
  </Card>
</CardGroup>

### Auto-Approve Patterns

Use **Always** strategically for low-risk, frequently-used commands:

**Safe patterns to auto-approve:**

```
kubectl get
kubectl describe
kubectl logs
git status
git log
git diff
ls
cat
pwd
docker ps
```

**Patterns to NEVER auto-approve:**

```
kubectl delete
kubectl apply
rm
git push
terraform apply
terraform destroy
npm publish
```

<Tip>
  Start with a minimal set of auto-approved commands. Add more as you build confidence in the patterns you use daily.
</Tip>

## Integrated Environment Workflows

### Chat + Terminal + Files

The power of Calmo Bridge IDE comes from using all three panels together:

**Workflow Example: Fixing a Configuration Bug**

1. **Chat** (right): "The API deployment is failing in staging"

2. **Terminal** (center bottom): See logs appear
   ```bash theme={null}
   $ kubectl logs deployment/api -n staging
   Error: ConfigMap 'api-config' not found
   ```

3. **File Browser** (left): Navigate to `kubernetes/staging/api/`

4. **Editor** (center top): Open `deployment.yaml`, spot the typo

5. **Edit** the file: Fix `api-confg` → `api-config`

6. **Chat**: "Apply the fixed deployment"

7. **Terminal**: Watch the apply succeed

All without leaving the Bridge IDE window.

### Context Switching Best Practices

**Efficient Navigation:**

* **Cmd/Ctrl+\`** - Toggle Terminal visibility
* **Cmd/Ctrl+/** - Focus Chat input
* **Click file** in tree - Open in editor
* **Click Terminal/Activity tabs** - Switch views

**Workflow Tips:**

* Keep relevant files open in tabs
* Use Terminal tab for active execution
* Switch to Activity tab to review history
* Minimize/maximize panels as needed

### Using Workspaces Effectively

**Organization:**

<Tabs>
  <Tab title="Do">
    ✅ **Add specific project directories**

    ```
    /Users/you/projects/frontend
    /Users/you/projects/backend
    /Users/you/infra/k8s-configs
    ```

    ✅ **Use workspace categories**

    * Git Repositories for app code
    * Terraform Projects for infrastructure
    * CI/CD Pipelines for deployment configs

    ✅ **Keep count manageable**

    * 3-10 workspaces is ideal
    * Remove when projects are archived
  </Tab>

  <Tab title="Don't">
    ❌ **Avoid adding entire home directory**

    ```
    /Users/you  # Too broad
    ```

    ❌ **Don't add system directories**

    ```
    /etc
    /var
    /usr/local
    ```

    ❌ **Don't duplicate workspaces**

    * Check "Current Workspaces" list before adding
    * One path per workspace
  </Tab>
</Tabs>

### File Editing Strategy

**When to edit in Bridge IDE:**

* Quick config tweaks
* Viewing files during chat
* Small changes suggested by Calmo
* Files you want to reference in conversation

**When to use your full IDE:**

* Large refactorings
* Complex multi-file changes
* Debugging sessions
* Long coding sessions

<Note>
  The Bridge IDE editor is designed for quick edits and AI collaboration, not as a full IDE replacement.
</Note>

## Workflow Optimization

### Effective Prompting

Be specific when asking Calmo to run commands:

**Good prompts:**

* "Check the logs for the api-server pod in the staging namespace, last 50 lines"
* "Show me all pods in CrashLoopBackOff state across all namespaces"
* "List recent commits in this repo with their authors"

**Less effective:**

* "Check the logs" (which pod? which namespace?)
* "What's wrong?" (too vague for targeted commands)

### Batch Operations

For multiple related operations, ask Calmo to handle them sequentially:

```
"First, check the pod status in production.
Then, describe any pods that aren't running.
Finally, show me the logs from failing containers."
```

Commands queue in the Approval panel. You can:

* Approve them one by one as you review
* Click **Allow** on all if they're safe
* Deny any that look incorrect

### Leveraging MCP Servers

Extend capabilities strategically:

| Use Case                | MCP Server              | Benefit                                      |
| ----------------------- | ----------------------- | -------------------------------------------- |
| Look up library docs    | context7                | Get up-to-date documentation for any library |
| Access project docs     | @mastra/mcp-docs-server | Quick reference to your framework docs       |
| Complex problem-solving | sequential-thinking     | Structured reasoning for debugging           |
| GitHub operations       | server-github           | Create PRs, list issues, manage repos        |

**Example Workflow:**

"Using the context7 tool, show me how to use React's useEffect hook with cleanup. Then, update the Timer.tsx file in my workspace to use it properly."

Calmo fetches the docs, understands your file, and suggests the edit.

## Development Workflows

### Kubernetes Debugging

A streamlined debugging session:

<Steps>
  <Step title="Get Overview">
    **Auto-approve** `kubectl get` patterns for quick status checks.

    Chat: "Show me all pods in staging"
  </Step>

  <Step title="Deep Dive">
    **Auto-approve** `kubectl describe` and `kubectl logs`.

    Chat: "Describe the failing pod and show me its logs"
  </Step>

  <Step title="Take Action">
    **Manually approve** any `kubectl delete`, `kubectl apply`, or `kubectl scale`.

    Chat: "Delete the crashlooping pod to restart it"

    Review the command, then click **Allow**.
  </Step>

  <Step title="Verify">
    **Auto-approved** get commands confirm the fix.

    Chat: "Check if the pod is healthy now"
  </Step>
</Steps>

### Infrastructure Changes

For Terraform or Kubernetes manifest changes:

1. **Edit in Bridge** - Make changes to YAML/HCL files
2. **Preview first** - Run `terraform plan` or `kubectl diff` (safe, auto-approve-able)
3. **Review changes** - Read the plan output in Terminal
4. **Apply intentionally** - Manually approve `terraform apply` or `kubectl apply`
5. **Verify** - Check resources with get commands

**Example:**

```
You: [Edit deployment.yaml to increase replicas]
You: "Apply this deployment to staging"
Calmo: kubectl apply -f deployment.yaml -n staging
[Command Approval panel shows MEDIUM RISK]
You: [Review, click Allow]
Terminal: deployment.apps/api configured
You: "How many replicas are running now?"
Calmo: kubectl get deployment api -n staging
Terminal: api  3/3  3  3  10s
```

### Git Operations

**Safe to auto-approve:**

* `git status`, `git log`, `git diff`
* `git branch -a`, `git remote -v`
* `git show <commit>`

**Manually approve:**

* `git commit` - Review commit message
* `git push` - Ensure correct branch
* `git merge` - Understand what's being merged
* `git checkout` - Verify branch/file changes

**Workflow:**

1. Chat: "Show me the status and recent changes"
2. Review output in Terminal
3. Chat: "Commit these changes with message: fix: correct API endpoint"
4. Review commit command, approve
5. Chat: "Push to feature branch"
6. Verify branch name, approve

## Performance Tips

### Keep Bridge IDE Running

Maintain state and connections by keeping Bridge IDE in the background:

* **Close window** → Minimizes to menu bar/tray
* **Connection persists** → No re-pairing needed
* **History preserved** → Command and chat history available
* **MCP servers stay connected** → No reload time

**When to restart:**

* After updating Bridge IDE version
* If memory usage is very high
* When troubleshooting connection issues

### Manage Pending Commands

Don't let commands queue indefinitely:

* **Approve or deny promptly** - Review and decide
* **Set up auto-approve** for safe patterns
* **Clear queue** if needed - Deny commands you don't need

### Regular Cleanup

**Clear Activity Log:**

* Click **Clear** in Activity tab when log grows large
* Doesn't affect command history with Calmo
* Frees up memory

**Close Unused Tabs:**

* Close file tabs you're no longer referencing
* Cmd/Ctrl+W to close active tab
* Right-click → Close All to clear all tabs

## Team Usage

If multiple team members use Calmo Bridge IDE:

### Individual Setup

* **Each person pairs their own machine** - One Bridge IDE per developer
* **Personal approval patterns** - Auto-approve lists are per-user
* **Individual workspaces** - Add your own project directories

### Shared Standards

Document across your team:

**Auto-Approve Patterns:**

```markdown theme={null}
# Team Auto-Approve Patterns

Safe for Always:
- kubectl get
- kubectl describe
- kubectl logs
- git status
- git log

Always Manual:
- kubectl delete
- kubectl apply
- terraform apply
- git push
```

**MCP Configuration:**

Share a base `mcp.json` template:

```json theme={null}
{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "${YOUR_KEY_HERE}"
      }
    },
    "sequential-thinking": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  }
}
```

**Workspace Guidelines:**

* Production systems → High scrutiny, minimal auto-approve
* Staging/dev → More auto-approve, faster iteration
* Local only → Maximum freedom

## What to Avoid

<Warning>
  **Security Anti-Patterns**

  ❌ Don't auto-approve destructive commands
  ❌ Don't add your entire home directory as a workspace
  ❌ Don't share `mcp.json` files with API keys
  ❌ Don't approve commands you don't understand
  ❌ Don't leave sensitive commands pending indefinitely
  ❌ Don't disable connection encryption/verification
</Warning>

**Workflow Anti-Patterns:**

* ❌ Editing production configs without review
* ❌ Running commands blindly without reading them
* ❌ Adding workspaces you don't actively use
* ❌ Keeping 50+ file tabs open
* ❌ Ignoring risk level indicators

## Quick Reference

### Risk Assessment Matrix

| Command Type      | Risk   | Auto-Approve?   | Examples                                            |
| ----------------- | ------ | --------------- | --------------------------------------------------- |
| Read operations   | Low    | ✅ Recommended   | `get`, `list`, `describe`, `logs`, `status`, `diff` |
| Plan/preview      | Low    | ✅ Recommended   | `terraform plan`, `kubectl diff`, `--dry-run`       |
| Write operations  | Medium | ⚠️ Case by case | `apply`, `create`, `scale`, `commit`                |
| Delete operations | High   | ❌ Never         | `delete`, `rm`, `destroy`, `drop`                   |
| Deploy/push       | High   | ❌ Never         | `push`, `publish`, `deploy` (to prod)               |

### Workspace Scope Guidelines

| Scope                 | Recommendation | Examples                               |
| --------------------- | -------------- | -------------------------------------- |
| Single project        | ✅ Ideal        | `/Users/you/projects/my-api`           |
| Related projects      | ✅ Good         | Multiple repos for one system          |
| Entire code directory | ⚠️ Broad       | `/Users/you/code` - consider splitting |
| Home directory        | ❌ Too broad    | `/Users/you` - security risk           |
| System directories    | ❌ Unnecessary  | `/etc`, `/var` - dangerous             |

### MCP Server Selection Guide

| Need                       | Recommended Server         | Configuration Type              |
| -------------------------- | -------------------------- | ------------------------------- |
| Library documentation      | context7                   | HTTP (requires API key)         |
| Framework docs (Mastra)    | @mastra/mcp-docs-server    | Stdio (npm package)             |
| Structured problem-solving | server-sequential-thinking | Stdio (npm package)             |
| GitHub integration         | server-github              | Stdio (requires GitHub token)   |
| Database queries           | server-postgres            | Stdio (requires DB credentials) |

## Troubleshooting Your Workflow

### Commands Taking Too Long

If commands seem slow:

1. **Check command scope** - Are you querying too much data?
   * Use `-n namespace` instead of `-A` (all namespaces)
   * Add `--tail=100` to log commands
   * Use `| head -n 20` to limit output

2. **Network latency** - Remote clusters take longer
   * Use `kubectl` contexts for faster access
   * Consider running commands on the cluster directly

3. **Optimize patterns** - Make commands more specific

### Losing Context in Chat

If Calmo seems to forget what you're working on:

1. **Reference open files** - "Look at the deployment.yaml I have open"
2. **Be explicit** - "In the staging namespace" instead of "there"
3. **Use workspace context** - Calmo sees your workspace structure
4. **Provide recent terminal output** - "Based on the logs you just showed me..."

### Terminal Output Hard to Read

If terminal output is difficult to parse:

1. **Use filtering** - `| grep`, `| less`, `| head`
2. **Request formatted output** - Ask Calmo to summarize
3. **Resize panels** - Drag dividers for more space
4. **Copy to editor** - Copy output, paste in new file for analysis

***

*For additional workflow guidance, contact our support team at [support@getcalmo.com](mailto:support@getcalmo.com).*