coder · EhabY · Mar 27, 2026
diff --git a/.vscodeignore b/.vscodeignore
@@ -45,5 +45,5 @@ node_modules/**
 
 # Documentation and media
 usage.md
-CLAUDE.md
+AGENTS.md
 *.gif
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,123 @@
+# Coder Extension Development Guidelines
+
+You are an experienced, pragmatic software engineer. Simple solutions
+over clever ones. Readability is a primary concern.
+
+## Our Relationship
+
+We're colleagues - push back on bad ideas and speak up when something
+doesn't make sense. Honesty over agreeableness.
+
+- Disagree when I'm wrong - act as a critical peer reviewer
+- Call out bad ideas, unreasonable expectations, and mistakes
+- Ask for clarification rather than making assumptions
+- Discuss architectural decisions before implementation;
+  routine fixes don't need discussion
+
+## Foundational Rules
+
+- Doing it right is better than doing it fast
+- YAGNI - don't add features we don't need right now
+- Make the smallest reasonable changes to achieve the goal
+- Reduce code duplication, even if it takes extra effort
+- Match the style of surrounding code - consistency within a file matters
+- Fix bugs immediately when you find them
+
+## Essential Commands
+
+| Task                      | Command                                             |
+| ------------------------- | --------------------------------------------------- |
+| **Build**                 | `pnpm build`                                        |
+| **Watch mode**            | `pnpm watch`                                        |
+| **Package**               | `pnpm package`                                      |
+| **Type check**            | `pnpm typecheck`                                    |
+| **Format**                | `pnpm format`                                       |
+| **Format check**          | `pnpm format:check`                                 |
+| **Lint**                  | `pnpm lint`                                         |
+| **Lint with auto-fix**    | `pnpm lint:fix`                                     |
+| **All unit tests**        | `pnpm test`                                         |
+| **Extension tests**       | `pnpm test:extension`                               |
+| **Webview tests**         | `pnpm test:webview`                                 |
+| **Integration tests**     | `pnpm test:integration`                             |
+| **Single extension test** | `pnpm test:extension ./test/unit/filename.test.ts`  |
+| **Single webview test**   | `pnpm test:webview ./test/webview/filename.test.ts` |
+
+## Testing
+
+- Test observable behavior and outputs, not implementation details
+- Descriptive names, minimal setup, no shared mutable state
+- Never mock in end-to-end tests; minimize mocking in unit tests
+- Find root causes, not symptoms - read error messages carefully
+- When mocking constructors (classes) with
+  `vi.mocked(...).mockImplementation()`, use regular functions, not arrow
+  functions. Arrow functions can't be called with `new`.
+
+```typescript
+// Wrong
+vi.mocked(SomeClass).mockImplementation(() => mock);
+// Correct
+vi.mocked(SomeClass).mockImplementation(function () {
+	return mock;
+});
+```
+
+### Test File Organization
+
+```text
+test/
+├── unit/           # Extension unit tests (mirrors src/ structure)
+├── webview/        # Webview unit tests (by package name)
+├── integration/    # VS Code integration tests (uses Mocha, not Vitest)
+├── utils/          # Test utilities that are also tested
+└── mocks/          # Shared test mocks
+```
+
+## Code Style
+
+- TypeScript with strict typing
+- Use Prettier for code formatting and ESLint for code linting
+- Use ES6 features (arrow functions, destructuring, etc.)
+- Use `const` by default; `let` only when necessary
+- Never use `any` - use exact types when possible
+- Avoid `as unknown as` - fix the types instead
+- Prefix unused variables with underscore (e.g., `_unused`)
+- Error handling: wrap and type errors appropriately
+- Use async/await for promises, avoid explicit Promise construction where
+  possible
+- Unit test files must be named `*.test.ts` and use Vitest
+- Extension tests go in `./test/unit/<path in src>`
+- Webview tests go in `./test/webview/<package name>/`
+- Never disable ESLint rules without user approval
+
+### Naming and Comments
+
+Names should describe what code does, not how it's implemented.
+
+Comments explain what code does or why it exists:
+
+- Never add comments about what used to be there or how things changed
+- Never use temporal terms like "new", "improved", "refactored", "legacy"
+- Code should be evergreen - describe it as it is
+- Do not add comments when you can instead use proper variable/function
+  naming
+
+### Avoid Unnecessary Changes
+
+When fixing a bug or adding a feature, don't modify code unrelated to your
+task. Unnecessary changes make PRs harder to review and can introduce
+regressions.
+
+Don't reword existing comments or code unless the change is directly
+motivated by your task. Don't delete existing comments that explain
+non-obvious behavior.
+
+When adding tests for existing behavior, read existing tests first to
+understand what's covered. Add cases for uncovered behavior. Edit existing
+tests as needed, but don't change what they verify.
+
+## Version Control
+
+- Commit frequently throughout development
+- Never skip or disable pre-commit hooks
+- Check `git status` before using `git add`
+- Don't use `git push --force` unless explicitly requested
diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -60,11 +60,17 @@ file to display network information.
 
 ## Other features
 
-There is a sidebar that shows all the user's workspaces, and all users'
-workspaces if the user has the required permissions.
+The extension provides several sidebar panels:
 
-There are also notifications for an outdated workspace and for workspaces that
-are close to shutting down.
+- **My Workspaces / All Workspaces** - tree views showing workspaces with status
+  indicators, quick actions, and search.
+- **Coder Tasks** - a React webview for creating, monitoring, and managing AI
+  agent tasks with real-time log streaming.
+- **Coder Chat** - an embedded chat UI for delegating tasks to AI coding agents
+  (gated behind the `coder.agentsEnabled` context flag).
+
+There are also notifications for outdated workspace templates and for workspaces
+that are close to shutting down.
 
 ## Webviews
 

diff --git a/README.md b/README.md
@@ -5,22 +5,39 @@
 [!["Join us on
 Discord"](https://badgen.net/discord/online-members/coder)](https://coder.com/chat?utm_source=github.com/coder/vscode-coder&utm_medium=github&utm_campaign=readme.md)
 
-The Coder Remote extension lets you open [Coder](https://github.com/coder/coder)
-workspaces with a single click.
+The Coder Remote extension connects your editor to
+[Coder](https://github.com/coder/coder) workspaces with a single click.
 
-- Open workspaces from the dashboard in a single click.
-- Automatically start workspaces when opened.
-- No command-line or local dependencies required - just install your editor!
-- Works in air-gapped or restricted networks. Just connect to your Coder
-  deployment!
-- Supports multiple editors: VS Code, Cursor, and Windsurf.
+![Demo](https://github.com/coder/vscode-coder/raw/main/demo.gif?raw=true)
 
-> [!NOTE]
-> The extension builds on VS Code-provided implementations of SSH. Make
-> sure you have the correct SSH extension installed for your editor
-> (`ms-vscode-remote.remote-ssh` or `codeium.windsurf-remote-openssh` for Windsurf).
+## Features
+
+- **One-click workspace access** - open workspaces from the Coder dashboard or
+  the editor sidebar. Workspaces start automatically when opened.
+- **Multi-editor support** - works with VS Code, Cursor, Windsurf, and other
+  VS Code forks.
+- **Workspace sidebar** - browse, search, and create workspaces. View agent
+  metadata and app statuses at a glance.
+- **Coder Tasks** - create, monitor, and manage AI agent tasks directly from
+  the sidebar with real-time log streaming.
+- **Coder Chat** - delegate development tasks to AI coding agents from the
+  sidebar. Requires [Coder Agents](https://coder.com/docs/ai-coder/agents) to
+  be enabled on your deployment.
+- **Multi-deployment support** - connect to multiple Coder deployments and
+  switch between them without losing credentials.
+- **Dev container support** - open dev containers running inside workspaces.
+- **Secure authentication** - session tokens stored in the OS keyring
+  (macOS/Windows), with optional OAuth 2.1 support.
+- **Air-gapped / restricted networks** - no external dependencies beyond your
+  Coder deployment.
+- **Automatic SSH tuning** - applies recommended SSH settings for reliable
+  long-lived connections and recovers from sleep/wake.
 
-![Demo](https://github.com/coder/vscode-coder/raw/main/demo.gif?raw=true)
+> [!NOTE]
+> The extension builds on VS Code-provided implementations of SSH. Make sure you
+> have the correct SSH extension installed for your editor
+> (`ms-vscode-remote.remote-ssh`, `anysphere.remote-ssh` for Cursor, or
+> `codeium.windsurf-remote-openssh` for Windsurf).
 
 ## Getting Started
 
@@ -34,11 +51,6 @@ ext install coder.coder-remote
 Alternatively, manually install the VSIX from the
 [latest release](https://github.com/coder/vscode-coder/releases/latest).
 
-### Variables Reference
-
-Coder uses `${userHome}` from VS Code's
+All extension settings are under the `coder.*` namespace in the Settings UI.
+Paths in settings accept `~` and `${userHome}` from VS Code's
 [variables reference](https://code.visualstudio.com/docs/editor/variables-reference).
-Use this when formatting paths in the Coder extension settings rather than `~`
-or `$HOME`.
-
-Example: ${userHome}/foo/bar.baz
diff --git a/package.json b/package.json
@@ -562,7 +562,7 @@
 		"@typescript-eslint/eslint-plugin": "^8.57.2",
 		"@typescript-eslint/parser": "^8.57.2",
 		"@vitejs/plugin-react": "catalog:",
-		"@vitest/coverage-v8": "^4.1.1",
+		"@vitest/coverage-v8": "^4.1.2",
 		"@vscode/test-cli": "^0.0.12",
 		"@vscode/test-electron": "^2.5.2",
 		"@vscode/vsce": "^3.7.1",
@@ -589,7 +589,7 @@
 		"typescript-eslint": "^8.57.2",
 		"utf-8-validate": "^6.0.6",
 		"vite": "catalog:",
-		"vitest": "^4.1.1"
+		"vitest": "^4.1.2"
 	},
 	"extensionPack": [
 		"ms-vscode-remote.remote-ssh"