# Zed AgentOps

Zed AgentOps helps you run an edit → verify → commit workflow inside Zed with a local MCP server and a project template designed for resumable agent work.

> Currently supported on macOS.

## What it does

- Creates a project template for using AgentOps in Zed
- Provides a local MCP server for repository, verification, and resume-oriented workflow helpers
- Adds default `verify` and `verify-release` entry points that you can extend for your project
- Keeps enough local state for the agent to resume work more reliably across interrupted sessions
- Aligns the generated project template, runtime workflow rules, and helper behavior around the supported v0.5.0 contract

This README is written for users of the tool. It focuses on how to set up and use AgentOps in practice.

## Installation

Install with Homebrew:

```bash
brew tap rioriost/agentops_mcp_server
brew install agentops_mcp_server
```

This installs:

- `agentops_mcp_server`
- `zed-agentops-init`

## Usage

### Zed configuration

Before you start using AgentOps in a project, configure Zed to use the MCP server.

For v0.5.0, this is effectively required. The intended workflow assumes:

- the MCP server is registered in Zed
- the Agent Panel can call the AgentOps tools it needs
- the commonly used AgentOps tools are pre-allowed in tool permissions

Add the MCP server to your Zed settings:

```json
{
  "agentops-server": {
    "command": "/opt/homebrew/bin/agentops_mcp_server",
    "args": [],
    "env": {
      "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
    }
  }
}
```

Then allow the MCP tools the workflow depends on. A practical baseline is:

```json
{
  "terminal": {
    "default": "allow"
  },
  "mcp:agentops-server:workspace_initialize": {
    "default": "allow"
  },
  "mcp:agentops-server:tx_event_append": {
    "default": "allow"
  },
  "mcp:agentops-server:tx_state_save": {
    "default": "allow"
  },
  "mcp:agentops-server:tx_state_rebuild": {
    "default": "allow"
  },
  "mcp:agentops-server:session_capture_context": {
    "default": "allow"
  },
  "mcp:agentops-server:repo_verify": {
    "default": "allow"
  },
  "mcp:agentops-server:repo_commit": {
    "default": "allow"
  },
  "mcp:agentops-server:repo_status_summary": {
    "default": "allow"
  },
  "mcp:agentops-server:repo_commit_message_suggest": {
    "default": "allow"
  },
  "mcp:agentops-server:tests_suggest": {
    "default": "allow"
  },
  "mcp:agentops-server:tests_suggest_from_failures": {
    "default": "allow"
  },
  "mcp:agentops-server:commit_if_verified": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_compact_context": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_handoff_export": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_resume_brief": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_start_task": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_update_task": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_end_task": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_add_file_intent": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_update_file_intent": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_complete_file_intent": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_capture_state": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_task_summary": {
    "default": "allow"
  },
  "mcp:agentops-server:ops_observability_summary": {
    "default": "allow"
  }
}
```

Adjust permissions to match your own security preferences, but if these tools are blocked the intended workflow will be incomplete.

### Initialize a project with `zed-agentops-init`

Create or update an AgentOps-managed project with:

```bash
zed-agentops-init my_project
```

or:

```bash
zed-agentops-init --update my_project
```

Use `--update` when you already have an older AgentOps template and want to refresh it to the current workflow contract.

#### What initialization creates

Running `zed-agentops-init` sets up the files you need to start using AgentOps in Zed:

- `.rules`
- `.zed/tasks.json`
- `.zed/scripts/verify`
- `.agent/tx_event_log.jsonl`
- `.agent/tx_state.json`

It also:

- creates a Git repository if one does not already exist
- appends common ignore entries to `.gitignore`
- preserves existing files when possible
- supports `--update` to refresh an existing setup

The baseline `.agent/tx_state.json` is intentionally a normalized empty-transaction state. It includes the major top-level fields and metadata needed for normal runtime interpretation, including:

- `schema_version`
- `active_tx`
- `last_applied_seq`
- `integrity.state_hash`
- `integrity.rebuilt_from_seq`
- `integrity.drift_detected`
- `integrity.active_tx_source`
- `updated_at`

This baseline is designed to be compatible with the richer runtime-rebuilt state shape without inventing runtime-only facts that can only be known after canonical event replay.

### Open the project in Zed

After initialization:

1. Open the project directory in Zed
2. Make sure your MCP server configuration is active
3. Open the Agent Panel
4. Confirm the agent can access the required AgentOps tools
5. Start work from the initialized repository root

For the supported workflow, the agent should initialize the workspace root before root-dependent operations and should treat `.agent/tx_state.json` and `.agent/tx_event_log.jsonl` as the canonical local workflow state.

### Configure `verify` / `verify-release` as needed

The generated template includes:

- `.zed/scripts/verify`
- `.zed/scripts/verify-release`

The default `verify` script is intentionally conservative. Extend it to match your project.

A common Python-oriented setup is:

- `verify`: fast local checks for day-to-day work
- `verify-release`: more complete checks for release-oriented validation

For example, in a Python project you may want:

- `.zed/scripts/verify` to run `ruff check`, `ruff format --check`, and `pytest -q`
- `.zed/scripts/verify-release` to run full coverage, such as `pytest --cov`

The default release-oriented coverage entry point is:

```bash
.zed/scripts/verify-release
```

This requires `pytest-cov` to be available if you use it for Python coverage.

### Initialize the language-specific project itself

AgentOps provides the workflow template, but it does not replace your language or package manager’s own project initialization.

For example, for a Python project with `uv` you might run:

```bash
uv init
```

Then add the checks your project needs to `.zed/scripts/verify` and `.zed/scripts/verify-release`.

Likewise, for other ecosystems you should initialize the actual project using the tools that ecosystem expects before asking the agent to make meaningful changes.

### Create a `docs` directory and write a draft

For the v0.5.0 workflow, it is useful to create a `docs` directory in the project and write a draft such as:

```text
docs/draft_0.1.0.md
```

This draft is where you describe:

- goals
- scope
- constraints
- priorities
- phases
- possible tickets

You can write the draft entirely yourself, or you can work with the AI agent to refine it. Both approaches are valid.

A practical pattern is:

1. Create `docs/`
2. Write an initial draft with the requirements you already know
3. Ask the agent to help refine the draft into a phase-oriented plan
4. If useful, maintain derived planning artifacts with the agent such as:
   - `docs/__version__/plan.md`
   - `docs/__version__/tickets_list.json`
   - `docs/__version__/pX-tY.json`
5. Use those planning files as workflow guidance while the work is in progress

A helpful way to think about the planning flow is:

- `draft.md` is the place to describe the problem, goals, scope, constraints, and priorities
- `plan.md` is the place to turn that draft into phased execution guidance
- `tickets_list.json` is a compact index of the tickets you intend to work through
- `pX-tY.json` files are optional per-ticket detail records for inputs, outputs, acceptance criteria, and notes

If you maintain ticket artifacts, a practical status set is:

- `planned`
- `in-progress`
- `checking`
- `verified`
- `committed`
- `done`
- `blocked`

Important v0.5.0 boundary:

- planning files under `docs/` are useful workflow artifacts
- they are not mandatory server-managed protocol state
- the server does not guarantee generation, synchronization, or validation of those planning artifacts for you
- if you choose to maintain them, keeping `tickets_list.json` and the per-ticket files in sync is recommended operating practice

They are best understood as user- or client-managed workflow documents.

## Updating from older versions

If you already use Zed AgentOps, run:

```bash
zed-agentops-init --update <project>
```

This refreshes the user-facing template, especially:

- `.rules`
- `.agent` state file presence
- default verify/task templates where applicable

Updating is recommended when moving from an older template, because recent versions tightened:

- resumability behavior
- transaction/state alignment
- workflow rule clarity
- template/runtime consistency

In most cases, `--update` is enough.

## What's new in v0.5.0

The most important user-facing changes in v0.5.0 are about clarity and predictability.

### 1. The documented workflow is closer to the real supported workflow

The main goal of v0.5.0 is to reduce mismatches between:

- `.rules`
- the generated template
- runtime server behavior
- helper tools
- release-facing documentation

As a user, that means the documented workflow is more trustworthy than before.

### 2. Ticket files are convention, not server protocol

If you keep planning files such as:

- `docs/__version__/plan.md`
- `docs/__version__/tickets_list.json`
- `docs/__version__/pX-tY.json`

they are useful workflow documents, but they are not canonical server-managed state.

In practice:

- you can maintain them manually
- you can maintain them together with the agent
- but you should not assume the server automatically creates, synchronizes, or validates them

### 3. The canonical local workflow state is under `.agent/`

For practical use, the most important canonical artifacts are:

- `.agent/tx_event_log.jsonl`
- `.agent/tx_state.json`

Handoff and planning docs are helpful, but they are not the canonical workflow record.

### 4. Commit workflow is more explicit

The supported flow is stricter:

- verify before commit
- no commit when there are no changes

This reduces accidental empty commits or unverified commits.

### 5. File-intent workflow is easier to use safely

The supported helper surface now includes:

- `ops_add_file_intent`
- `ops_update_file_intent`
- `ops_complete_file_intent`

These helpers make common file-intent workflows easier to follow without weakening the canonical transaction rules.

### 6. Bootstrap state is easier to reason about

The initial `.agent/tx_state.json` baseline is more normalized, so users and clients are less likely to misread missing fields as ambiguous old-template behavior.

### 7. Version concepts are intentionally distinct

You may see different version concepts, and they do not all mean the same thing:

- package/server version
- transaction/schema version
- draft/release-plan version

This is expected. Do not assume that a docs version label is automatically the same thing as the persisted transaction schema version.

### Practical recommendations for users

For day-to-day use in v0.5.0:

1. Keep your template current with `zed-agentops-init --update` when needed
2. Treat `.agent/tx_state.json` and `.agent/tx_event_log.jsonl` as the canonical local workflow state
3. Treat planning files under `docs/` as useful convention, not guaranteed server protocol
4. Extend `verify` and `verify-release` to match your project
5. Prefer small, clearly scoped drafts in `docs/` before large agent-driven work
6. Expect the agent workflow to follow initialize → change → verify → commit more strictly than before

For a fuller release-facing explanation of the supported v0.5.0 client/server contract, see `docs/v0.5.0/interoperability.md`.

## Notes

- macOS only at the moment
- The generated template is meant to be customized per repository
- The default verify scripts are intentionally conservative and may need project-specific additions
- The v0.5.0 workflow distinguishes between enforced protocol behavior and user-managed workflow convention; that distinction is intentional

## License

MIT
