zedcopilotkit

Agentic engineering kit for Zed and GitHub Copilot.

Token-efficient. HITL-first. Anti-slop. Built for real development.

What this is

zedcopilotkit is a lightweight kit that helps you turn Zed into a structured, auditable engineering workflow.

It focuses on:

• project-level rules and instructions
• a Zed-native .rules entrypoint
• local MCP servers for cross-session continuity
• semantic and structural search for code exploration
• strict tool permissions for human-in-the-loop workflows
• model presets for task-appropriate efficiency

Quick start

npx zedcopilotkit init

Then:

1. Open the project in Zed
2. Read .rules
3. Install the local MCP server dependencies
4. Run osgrep setup and osgrep index
5. Start using the agent workflow

Dependency classes

Mandatory

• Node.js 18+
• rtk

Recommended

• osgrep
• ast-grep

Optional

• pbakaus/impeccable skill pack
• remote MCP servers like exa

Recommended model presets

These presets favour token efficiency first, then reasoning quality.

| Preset | Default model | Inline assistant | Commit messages | Thread summaries | Best for | |---|---|---|---|---|---| | balanced | claude-sonnet-4.6 | gpt-5-mini | gpt-5-nano | gpt-5-nano | day-to-day coding with good reasoning and low token cost | | cheap-fast | gpt-5-mini | gpt-5-nano | gpt-5-nano | gpt-5-nano | quick tasks, summaries, and low-cost iteration | | reasoning-heavy | claude-sonnet-4.6 | claude-haiku-4.5 | gpt-5-nano | gpt-5-nano | planning, refactors, and harder engineering tasks |

Notes:

• Keep the default model strong enough for reasoning.
• Use cheaper models for summaries and commit messages.
• Start with balanced if you want the safest general-purpose option.

What gets installed

.github/
  copilot-instructions.md     ← Copilot instructions

.rules                        ← Zed-native default rules entrypoint
AGENTS.md                     ← compatibility bridge for other agents

.zed/
  mcp-config.json             ← MCP servers config only

.agent/
  instructions.md             ← full internal contract
  catalog.md                  ← skills and tools index
  .agentignore                ← files the agent must never read
  system-prompts/
    anti-slop.md              ← hard behavioural rules
  skills/
    osgrep.md                 ← semantic search strategy
    ast-grep.md               ← structural search patterns
    context-map.md            ← blast radius analysis
  planning/
    task_plan.md              ← template: phases + decisions
    findings.md               ← template: research + discoveries
    progress.md               ← template: session log
  scripts/
    verify.sh                 ← lint → typecheck → tests
    plan.sh                   ← create a new plan file
    env-loader.sh             ← load .env safely (no echo)
  mcp-servers/
    state-server/             ← cross-session task memory

Setup after install

1. Install MCP state server dependencies:

cd .agent/mcp-servers/state-server && npm install && cd -

2. Configure Zed MCP settings in .zed/mcp-config.json:

   • local MCP servers for agent-state, osgrep, and ast-grep
   • remote MCP servers like exa can be added as URL-based entries

3. Open the project in Zed and let .rules provide the default behaviour:

   • .rules is the primary Zed entrypoint
   • AGENTS.md is a compatibility bridge
   • .agent/instructions.md is the detailed internal contract

4. Prepare osgrep:

osgrep setup
osgrep index

5. Open Zed and read the agent contract:

@.agent/instructions.md

Usage

Daily workflow

1. Open Zed
2. Ask your question or describe the task
3. The agent follows the contract and tool permissions automatically
4. Use .rules first, then AGENTS.md, then .agent/instructions.md if needed

For better token efficiency:

• use the main agent thread for reasoning-heavy tasks
• use the inline assistant for short local edits
• use thread summaries to compress long sessions

For complex tasks, load context explicitly in Zed chat:

@.agent/instructions.md
@task_plan.md
What is the next step for the auth refresh feature?

Before editing files

The agent should:

1. search with osgrep and ast-grep
2. build a context map
3. classify risk level
4. for Medium/High risk: write a plan and stop for approval
5. follow .rules first, then AGENTS.md, then .agent/instructions.md

Running verification

.agent/scripts/verify.sh        # lint → typecheck → tests
.agent/scripts/verify.sh --fix  # attempt auto-fix on failures

Creating a plan

.agent/scripts/plan.sh add-auth-refresh
# creates: .agent/plans/2025-01-15-add-auth-refresh.md

Adding optional skills

# Frontend design (typography, color, spatial, motion, interaction)
npx zedcopilotkit add-skill pbakaus/impeccable

# Single skill from a pack
npx zedcopilotkit add-skill pbakaus/impeccable/polish

After adding, update .agent/catalog.md to reference the new skill.

Persisting task state across sessions

Zed MCP is configured through context_servers in .zed/mcp-config.json.

The state server is intentionally small and local:

• save_task_state
• load_task_state
• list_task_states

Use it for cross-session continuity, but keep human approval for risky actions.

In Zed's assistant panel, the MCP tools are available:

save_task_state — id: "add-auth-refresh", data: { summary: "...", nextSteps: [...] }
load_task_state — id: "add-auth-refresh"
list_task_states

CLI reference

npx zedcopilotkit init              # install into current project
npx zedcopilotkit init --force      # overwrite existing files
npx zedcopilotkit update            # update to latest version
npx zedcopilotkit add-skill <src>   # add skills from GitHub
npx zedcopilotkit doctor            # check prerequisites

How the agentic components map to this kit

| Agentic component | Implementation | |---|---| | CoT / Reasoning | anti-slop protocol forces structured reasoning before acting | | ReAct loop | instructions.md solver loop: Locate → Map → Plan → Execute → Verify | | Self-reflection | 3-strike auto-fix in verify.sh; update progress.md after failures | | Plan & Execute | plan.sh + .agent/plans/ + risk levels + HITL gates | | Context window | .agentignore + osgrep skeleton (skeleton-first reads) | | RAG / Grounding | osgrep index — local semantic search, no API calls | | Short-term memory | context window + task_plan.md | | Long-term memory | MCP state server (save_task_state / load_task_state) | | State management | task_plan.md + findings.md + progress.md on disk | | Tool / function calling | MCP tools via Zed assistant panel | | HITL | .rules → risk classification → plan → explicit human approval required | | Orchestrator | instructions.md agent contract | | Sandboxing | .agentignore blocks secrets + artifacts; env-loader.sh no-echo | | Evaluators | verify.sh chain (lint → typecheck → test) | | Prompt leakage | .agentignore + env-loader.sh + secrets never echoed |

What Zed + Copilot can and cannot do

Can do natively:

• project rules and instructions
• MCP tool calls
• file context injection
• inline assistant transformations
• edit prediction / completions
• tool permissions

Requires this kit:

• semantic search (osgrep)
• structural search (ast-grep)
• token compression wrapper (rtk)
• planning files on disk (task_plan.md, findings.md, progress.md)
• cross-session memory (agent-state MCP server)
• HITL gates (.rules, AGENTS.md, .github/copilot-instructions.md, .agent/instructions.md)

Not the core focus:

• text threads for agentic workflows
• external agents for the main harness loop

Docs

Deep dives live in docs/:

• docs/README.md
• docs/01-overview.md
• docs/02-zed-native.md
• docs/03-mcp-and-memory.md
• docs/04-tool-permissions.md
• docs/05-reasoning-patterns.md
• docs/06-model-presets.md
• docs/07-safety-and-hitl.md

Built on

| Project | License | Role | |---|---|---| | rtk-ai/rtk | MIT | CLI token proxy | | Ryandonofrio3/osgrep | Apache-2.0 | Semantic code search | | ast-grep/ast-grep | MIT | Structural code search | | pbakaus/impeccable | Apache-2.0 | Optional frontend design skills |

License

MIT