mirror of
https://github.com/CopilotKit/CopilotKit.git
synced 2026-09-14 16:26:20 +08:00
docs: refactor AGENTS.md and CLAUDE.md with progressive disclosure (#3259)
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Alem Tuzlak
@@ -0,0 +1,75 @@
|
||||
# Architecture & Packages
|
||||
|
||||
## Three-Layer Architecture
|
||||
|
||||
```
|
||||
Frontend (React/Angular/Vanilla) → Runtime (Express/Hono server) → Agent (LangGraph/CrewAI/BuiltIn/Custom)
|
||||
```
|
||||
|
||||
All layers communicate via the **AG-UI protocol** — an event-based standard streamed over SSE.
|
||||
|
||||
## V1 vs V2
|
||||
|
||||
V2 (`@copilotkitnext/`) is the real implementation. V1 (`@copilotkit/`) is the public API that wraps V2 internally. New features always go in V2. If V1 compatibility is needed, create a thin re-export or wrapper in the corresponding V1 package.
|
||||
|
||||
## V2 Packages
|
||||
|
||||
- **shared**: Common utilities, types, and constants used across all other packages.
|
||||
- **core**: The `CopilotKitCore` orchestrator — the central brain on the frontend. Manages the agent registry, tool registry, context store, and event subscriptions. All framework packages (React, Angular, Vanilla) wrap this.
|
||||
- **react**: React hooks (`useAgent`, `useFrontendTool`, `useAgentContext`, etc.) and `CopilotKitProvider`. Hooks are thin wrappers that register/unregister with `CopilotKitCore` on mount/unmount.
|
||||
- **angular**: Angular DI tokens, services, and signal-based state. Same concepts as React but using Angular patterns (`inject()`, signals, `AgentStore`).
|
||||
- **runtime**: The server-side `CopilotRuntime` class that receives HTTP requests and delegates to agents. Provides Express and Hono adapters. Contains the `AgentRunner` abstraction for managing thread/conversation state.
|
||||
- **agent**: The `BuiltInAgent` — a default agent implementation powered by the Vercel AI SDK. Used when developers don't bring their own agent framework.
|
||||
- **voice**: Voice input and transcription support.
|
||||
- **web-inspector**: A debug console (Lit web component) for inspecting agent communication in development.
|
||||
- **sqlite-runner**: An `AgentRunner` implementation that persists thread state to SQLite instead of memory.
|
||||
|
||||
## V1 Packages
|
||||
|
||||
- **react-core**: The public `<CopilotKit>` provider and hooks. Internally delegates to V2 core.
|
||||
- **react-ui**: Chat UI components — `CopilotChat`, `CopilotPopup`, `CopilotSidebar`, `CopilotPanel`.
|
||||
- **react-textarea**: The `CopilotTextarea` component for AI-assisted text editing.
|
||||
- **shared**: Shared types and telemetry utilities.
|
||||
- **runtime**: Server-side runtime with GraphQL server and LLM adapters.
|
||||
- **runtime-client-gql**: urql-based GraphQL client for frontend-to-runtime communication.
|
||||
- **sdk-js**: Helpers for LangGraph/LangChain agent integration.
|
||||
|
||||
## Request Lifecycle
|
||||
|
||||
1. **Init**: Frontend creates `CopilotKitCore` → fetches agent info from runtime → creates a `ProxiedAgent` instance per remote agent.
|
||||
2. **User sends message**: Message is added to the agent, then `runAgent()` is called.
|
||||
3. **HTTP request**: A POST is sent to the runtime with a `RunAgentInput` payload containing messages, registered tools, context, threadId, and state.
|
||||
4. **Runtime processing**: Request middleware runs → agent is resolved and cloned → `AgentRunner` executes the agent.
|
||||
5. **SSE stream back**: Agent emits AG-UI events streamed to the frontend: run lifecycle events, text message chunks (streaming), and optional tool call events.
|
||||
6. **Frontend tool execution**: When the agent calls a frontend tool, Core looks up the handler in its registry, executes it locally in the browser, and sends the result back to the agent which continues processing.
|
||||
7. **UI update**: Core updates its message store and notifies subscribers → React/Angular re-renders.
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### AG-UI Protocol
|
||||
|
||||
All agent↔UI communication is event-based. Events follow a structured lifecycle: `RUN_STARTED` → `STEP_STARTED` → message/tool events → `STEP_FINISHED` → `RUN_FINISHED`. Events are streamed over SSE and validated with Zod schemas. The `EventType` enum in `@ag-ui/core` defines all event types.
|
||||
|
||||
### ProxiedAgent
|
||||
|
||||
The frontend representation of a remote agent. Implements the `AbstractAgent` interface but translates calls into HTTP requests to the runtime, streaming SSE events back. Created automatically when the runtime reports available agents.
|
||||
|
||||
### AgentRunner
|
||||
|
||||
An abstract class on the runtime side responsible for managing thread state (conversation history, agent state). The default `InMemoryAgentRunner` is ephemeral; `SQLiteAgentRunner` provides persistence. Custom runners can be built for any storage backend.
|
||||
|
||||
### Tool Registration
|
||||
|
||||
Tools can be **frontend tools** (handler runs in the browser, registered via `useFrontendTool`) or **backend tools** (handler runs on the server, defined in the agent config). Tools can be scoped to a specific agent via `agentId`, or available to all agents by omitting it.
|
||||
|
||||
### Context
|
||||
|
||||
Application data sent alongside messages to give agents awareness of the current UI state. Registered via `useAgentContext(description, data)` where data is any JSON-serializable value. Automatically included in every agent run.
|
||||
|
||||
### Multi-Agent
|
||||
|
||||
Multiple agents can be registered in a single `CopilotRuntime`. Each agent gets its own endpoint, message thread, state, and optionally scoped tools. The frontend selects which agent to interact with via `useAgent({ agentId })`.
|
||||
|
||||
### Middleware
|
||||
|
||||
`CopilotRuntime` supports `beforeRequestMiddleware` and `afterRequestMiddleware` for cross-cutting concerns like authentication, logging, and request/response transformation.
|
||||
@@ -0,0 +1,27 @@
|
||||
# Git & PRs
|
||||
|
||||
## Worktree Workflow
|
||||
|
||||
Always use a git worktree for non-trivial work. This keeps the main working tree clean and lets you work in isolation.
|
||||
|
||||
1. **Start a worktree** at the beginning of a task. This creates a new branch and a separate working directory.
|
||||
2. **Do all work** inside the worktree — commits, builds, tests.
|
||||
3. **Push the worktree branch** to the remote with `-u` to set up tracking.
|
||||
4. **Create a PR** targeting `main` using `gh pr create --base main`.
|
||||
5. **Clean up** the worktree after the PR is merged.
|
||||
|
||||
## Creating a PR
|
||||
|
||||
When the work is ready:
|
||||
|
||||
1. Stage and commit your changes in the worktree.
|
||||
2. Push the branch: `git push -u origin <branch-name>`
|
||||
3. Create the PR: `gh pr create --base main`
|
||||
4. Use a clear title (under 70 chars) and a body summarizing what changed and why.
|
||||
|
||||
## Commit Conventions
|
||||
|
||||
- Write concise commit messages focused on the "why", not the "what".
|
||||
- Stage specific files — avoid `git add -A` or `git add .` to prevent accidentally including unrelated changes.
|
||||
- Never amend commits unless explicitly asked. Always create new commits.
|
||||
- Never force-push unless explicitly asked.
|
||||
@@ -0,0 +1,8 @@
|
||||
# Hook Development
|
||||
|
||||
When creating a new hook, always complete **all** of the following:
|
||||
|
||||
1. **Implementation**: Create the hook in the V2 react package. If V1 compatibility is needed, add a re-export in the V1 react-core package.
|
||||
2. **JSDoc**: Add JSDoc on top of the hook implementation, including usage examples.
|
||||
3. **Tests**: Write extensive tests covering behavior, edge cases, and lifecycle (mount/unmount/re-render).
|
||||
4. **Documentation**: Add a dedicated docs page under `/docs` and update the relevant docs metadata file(s) so the page appears in navigation.
|
||||
@@ -0,0 +1,30 @@
|
||||
# Workflow & Process
|
||||
|
||||
## When to Plan vs. Fix Autonomously
|
||||
|
||||
- **Bug fixes** (small/medium, < 5 files): Fix autonomously. No plan mode, no check-in. Just fix it, run tests, done.
|
||||
- **Large bugs** (5+ files or architectural impact): Enter plan mode first.
|
||||
- **New features and refactors**: Always enter plan mode. Get user sign-off on the approach before implementing.
|
||||
|
||||
## Planning
|
||||
|
||||
- Enter plan mode for non-trivial features and refactors.
|
||||
- Write the plan to `tasks/todo.md` with checkable items.
|
||||
- If something goes sideways during implementation, stop and re-plan — don't push through a broken approach.
|
||||
|
||||
## Verification
|
||||
|
||||
- Never mark a task complete without proving it works.
|
||||
- Run tests and check for regressions.
|
||||
- Diff behavior between main and your changes when relevant.
|
||||
|
||||
## Bug Fixing
|
||||
|
||||
- When given a bug report: find the root cause, fix it, verify. No hand-holding needed.
|
||||
- Point at logs, errors, failing tests — then resolve them.
|
||||
- Go fix failing CI tests without being told how.
|
||||
|
||||
## Self-Improvement
|
||||
|
||||
- After any correction from the user: update `tasks/lessons.md` with the pattern and a rule to prevent it.
|
||||
- Review lessons at session start.
|
||||
@@ -13,11 +13,20 @@
|
||||
|
||||
<!-- nx configuration end-->
|
||||
|
||||
# Hook Development Requirements
|
||||
# CopilotKit
|
||||
|
||||
When creating a new hook, always complete all of the following:
|
||||
AI agent framework with three layers: **Frontend** (React/Angular/Vanilla) → **Runtime** (Express/Hono) → **Agent** (LangGraph/CrewAI/BuiltIn/Custom), communicating via the AG-UI protocol (event-based SSE).
|
||||
|
||||
- Add dedicated documentation for the hook under `/docs`.
|
||||
- Update the relevant docs metadata file(s) so the page appears in docs navigation.
|
||||
- Add JSDoc on top of the hook implementation, including usage examples.
|
||||
- Write extensive tests for the hook (covering behavior, edge cases, and lifecycle where applicable).
|
||||
## Essentials
|
||||
|
||||
- **Nx monorepo** — always run tasks through `nx` (`nx run`, `nx run-many`, `nx affected`), never the underlying tooling directly.
|
||||
- **V1 wraps V2** — V2 (`@copilotkitnext/`) is the real implementation. V1 (`@copilotkit/`) is the public compatibility layer that delegates to V2. Build new features in V2 first. Add V1 wrappers only if backward compatibility is needed.
|
||||
- **Simplicity** — prefer the simplest correct solution. For non-trivial changes, consider if there's a cleaner approach before committing.
|
||||
- **Worktrees** — always work in a git worktree for isolation. See [Git & PRs](.claude/docs/git.md) for the full workflow.
|
||||
|
||||
## Reference (read when relevant to your task)
|
||||
|
||||
- [Architecture & Packages](.claude/docs/architecture.md) — V2/V1 package roles, request lifecycle, core concepts (AG-UI, ProxiedAgent, AgentRunner, tools, context, multi-agent)
|
||||
- [Hook Development](.claude/docs/hooks.md) — checklist for creating new hooks (docs, tests, JSDoc)
|
||||
- [Workflow & Process](.claude/docs/workflow.md) — when to plan, when to fix autonomously, verification, self-improvement loop, this should be your default mindset when working on any task
|
||||
- [Git & PRs](.claude/docs/git.md) — worktree workflow, branching, creating PRs
|
||||
|
||||
@@ -13,11 +13,20 @@
|
||||
|
||||
<!-- nx configuration end-->
|
||||
|
||||
# Hook Development Requirements
|
||||
# CopilotKit
|
||||
|
||||
When creating a new hook, always complete all of the following:
|
||||
AI agent framework with three layers: **Frontend** (React/Angular/Vanilla) → **Runtime** (Express/Hono) → **Agent** (LangGraph/CrewAI/BuiltIn/Custom), communicating via the AG-UI protocol (event-based SSE).
|
||||
|
||||
- Add dedicated documentation for the hook under `/docs`.
|
||||
- Update the relevant docs metadata file(s) so the page appears in docs navigation.
|
||||
- Add JSDoc on top of the hook implementation, including usage examples.
|
||||
- Write extensive tests for the hook (covering behavior, edge cases, and lifecycle where applicable).
|
||||
## Essentials
|
||||
|
||||
- **Nx monorepo** — always run tasks through `nx` (`nx run`, `nx run-many`, `nx affected`), never the underlying tooling directly.
|
||||
- **V1 wraps V2** — V2 (`@copilotkitnext/`) is the real implementation. V1 (`@copilotkit/`) is the public compatibility layer that delegates to V2. Build new features in V2 first. Add V1 wrappers only if backward compatibility is needed.
|
||||
- **Simplicity** — prefer the simplest correct solution. For non-trivial changes, consider if there's a cleaner approach before committing.
|
||||
- **Worktrees** — always work in a git worktree for isolation. See [Git & PRs](.claude/docs/git.md) for the full workflow.
|
||||
|
||||
## Reference (read when relevant to your task)
|
||||
|
||||
- [Architecture & Packages](.claude/docs/architecture.md) — V2/V1 package roles, request lifecycle, core concepts (AG-UI, ProxiedAgent, AgentRunner, tools, context, multi-agent)
|
||||
- [Hook Development](.claude/docs/hooks.md) — checklist for creating new hooks (docs, tests, JSDoc)
|
||||
- [Workflow & Process](.claude/docs/workflow.md) — when to plan, when to fix autonomously, verification, self-improvement loop, this should be your default mindset when working on any task
|
||||
- [Git & PRs](.claude/docs/git.md) — worktree workflow, branching, creating PRs
|
||||
|
||||
Reference in New Issue
Block a user