diff --git a/docs/contributing/ai.md b/docs/contributing/ai.md index 0954e42df..bab6290e8 100644 --- a/docs/contributing/ai.md +++ b/docs/contributing/ai.md @@ -47,219 +47,10 @@ language model and flexible integration capabilities through the Model Context P allows us to create custom workflows and integrate with our existing development tools while maintaining control over data privacy and security. -## Installing Claude Code and Claude Desktop +:::tip Setting up AI tooling -### Claude Code +To set up AI tooling in your development environment, see the +[AI Tools](./../getting-started/tools/index.md#ai-tools) instructions of our Getting Started +section. -Claude Code is Anthropic's official CLI tool that brings Claude's capabilities directly to your -terminal. It's ideal for developers who prefer command-line interfaces and want to integrate AI -assistance into their terminal-based workflows. - -#### Installation - -1. [Node.js](https://nodejs.org/) v18 or higher is available -2. Install via NPM `npm install -g @anthropic-ai/claude-code` or Homebrew - `brew install --cask claude-code` -3. Configure your API key: - - ```bash - claude configure - ``` - - Walk through the process to sign into the Anthropic Console via SSO and authenticate your local - client. - -#### Basic usage - -```bash -# Start an interactive session -claude - -# Ask a question -claude "How do I add a feature flag around my changes?" -``` - -### Claude Desktop - -Claude Desktop provides a graphical interface for interacting with Claude, ideal for developers who -prefer a dedicated application with rich formatting and file management capabilities. - -#### Installation - -Install via [claude.ai/download](https://claude.ai/download) or Homebrew `brew install claude` - -- Launch Claude Desktop -- Sign in with your Anthropic account via SSO -- Configure your workspace preferences -- Enable MCP server connections in Settings → Developer → MCP Servers - -## MCP servers and extensions - -Model Context Protocol (MCP) servers extend Claude's capabilities by providing access to external -tools, APIs, and data sources. They enable Claude to interact with your development environment, -databases, and other services while maintaining security boundaries. - -### Bitwarden AI plugin marketplace - -Bitwarden maintains a curated [marketplace of AI plugins](https://github.com/bitwarden/ai-plugins) -specifically designed for our development workflows. This marketplace was created to provide -quality-controlled, security-reviewed plugins that follow Bitwarden's coding standards and security -requirements. All marketplace plugins are maintained by the Bitwarden team and include comprehensive -documentation, testing, and security validation. - -To use the marketplace with Claude Code: - -```bash -/plugin marketplace add bitwarden/ai-plugins -``` - -### Understanding MCP servers - -MCP servers are separate processes that communicate with Claude through a standardized protocol. -They can: - -- Access local file systems and databases -- Execute commands and scripts -- Integrate with third-party APIs -- Provide specialized reasoning capabilities - -We recommend at least two be installed by everyone: - -### Installing Sequential Thinking MCP server - -The Sequential Thinking server enhances Claude's problem-solving capabilities by providing -structured, step-by-step reasoning for complex tasks. - -#### Claude Code - -```bash -claude mcp add --scope user sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking -``` - -#### Claude Desktop - -Edit your `~/.claude.json`, go to the `mcpServers` section and add: - -```json -"sequential-thinking": { - "type": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-sequential-thinking" - ] - } -``` - -Restart Claude Desktop to activate the server. - -### Installing Memory MCP server - -The Memory server provides Claude with persistent memory capabilities, allowing it to remember -context across sessions and maintain a knowledge graph of your projects. - -#### Claude Code - -```bash -claude mcp add --scope user memory -- npx -y @modelcontextprotocol/server-memory -``` - -#### Claude Desktop - -Edit your `~/.claude.json`, go to the `mcpServers` section and add: - -```json -"memory": { - "type": "stdio", - "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-memory" - ] - } -``` - -Restart Claude Desktop to activate the server. - -### Verifying installations - -#### Claude Code - -```bash -claude mcp list -``` - -#### Claude Desktop - -1. Open Claude Desktop -2. Start a new conversation -3. Type: "Can you list your available MCP servers?" -4. Claude should respond with the configured servers - -### Troubleshooting - -Common issues and solutions: - -**Server not starting**: - -- Verify NPM packages are installed globally -- Check Node version (must be 18+) -- Review server logs in `~/.claude-code/logs/` or Claude Desktop's developer console - -**Permission errors**: - -- Ensure data directories have proper permissions -- On macOS/Linux: `chmod 755 ~/.claude-memory` - -**Configuration not loading**: - -- Validate JSON syntax in configuration files -- Restart Claude Code or Claude Desktop after configuration changes - -### Best practices - -**Security considerations**: - -- Only install MCP servers from trusted sources -- Review server permissions and capabilities before installation: - - Examine the server's source code or documentation to understand what file system access it - requires - - Verify what external APIs or services the server connects to - - Check if the server executes system commands and understand which ones - - Confirm whether the server stores persistent data and where it's stored - - Review network permissions and ensure the server only communicates with expected endpoints - - Validate that the server follows principle of least privilege -- Use trusted LLM providers and models: - - Prefer established providers with strong security track records (e.g., Anthropic) - - Verify the provider's data handling policies and ensure they align with Bitwarden's security - requirements - - Confirm that your API keys and credentials are stored securely - - Understand whether your prompts and code are used for model training (opt out if possible) - - Use enterprise or business tier services when available for enhanced security guarantees -- Core model usage guidelines: - - Use the latest stable model versions to benefit from security improvements and bug fixes - - Avoid deprecated or experimental models in production workflows - - Be aware of model capabilities and limitations - not all models are suitable for code generation - - Consider model context windows and token limits when designing workflows - - Use model-specific features (like Claude's extended thinking) appropriately for complex tasks - - Monitor model output for hallucinations or incorrect information, especially in - security-critical code -- Regularly update servers to get security patches - -**Performance optimization**: - -- Limit the number of active servers to those you actively use -- Monitor resource usage, especially for memory-intensive servers -- Configure appropriate timeouts for long-running operations - -**Data management**: - -- Regularly backup memory server data directories -- Clear old session data periodically to maintain performance -- Use project-specific memory contexts when appropriate - -**Integration with development workflow**: - -- Configure project-specific MCP servers in repository `.claude/` directories -- Document custom MCP server requirements in project README files -- Share MCP configurations with team members for consistency +::: diff --git a/docs/contributing/template-repository.md b/docs/contributing/template-repository.md index db9035bd4..096bb0b0b 100644 --- a/docs/contributing/template-repository.md +++ b/docs/contributing/template-repository.md @@ -123,7 +123,7 @@ Initial content placeholders provide AI assistance and automated code reviews: ``` Project settings contain useful configuration such as -[our marketplace](./ai.md#bitwarden-ai-plugin-marketplace). +[our marketplace](./../getting-started/tools/index.md#bitwarden-ai-plugin-marketplace). ### Automated reviews diff --git a/docs/getting-started/tools/index.md b/docs/getting-started/tools/index.md index 4336425dc..0a2b6779d 100644 --- a/docs/getting-started/tools/index.md +++ b/docs/getting-started/tools/index.md @@ -4,19 +4,17 @@ sidebar_position: 1 # Tools -## Operating system +:::warning Operating system assumptions -All Bitwarden developers are issued with a MacBook. The tooling recommendations and instructions in -this documentation assume that you’re using macOS. This may require some adaptation if you’re using -a different operating system. +The tooling recommendations and instructions in this documentation assume that you’re using macOS. +This may require some adaptation if you’re using a different operating system. -## Recommended tools +::: -The following tools are strongly recommended as part of the “standard” developer setup. We recommend -that any new Bitwarden developer install all of them as part of setting up their local development -environment. +The following tools make up the standard Bitwarden developer setup and should be installed as part +of your local development environment. -### IDEs +## IDEs - [Visual Studio Code](https://code.visualstudio.com/) - used for all Typescript projects. Suboptimal for C#. Be sure to install [extensions](#visual-studio-code-extensions) @@ -25,7 +23,7 @@ environment. - [Xcode](https://developer.apple.com/xcode/) - required for iOS Mobile development and Safari web extension -### Local environment +## Local environment - [Homebrew](https://brew.sh/) - package manager for macOS - [Iterm2](https://iterm2.com/) (available via Homebrew) - a better terminal emulator @@ -43,9 +41,8 @@ environment. [rustup](https://rustup.rs/)) - [Git](https://git-scm.com) - [Commit signing](../../contributing/commit-signing.mdx) is strongly recommended -- [AI tools](../../contributing/ai.md) -### Mobile +## Mobile - [Android Studio](https://developer.android.com/studio/) - Nice for setting up and running Android Simulators @@ -53,7 +50,7 @@ environment. - [Apple Icons Generator Gist](https://gist.github.com/brutella/0bcd671a9e4f63edc12e) - Script to generate Apple icons from an image -### Databases +## Databases - [MSSQL VSCode Extension](https://marketplace.visualstudio.com/items?itemName=ms-mssql.mssql) for working with your local SQL Server @@ -61,7 +58,7 @@ environment. - [MySQLWorkbench](https://www.mysql.com/products/workbench/) - Useful for fiddling with MySQL db - [SQLiteStudio](https://www.sqlitestudio.pl/) - Useful for fiddling with SQLite db -### Visual Studio Code Extensions +## Visual Studio Code extensions There are some vs code extensions that are life-savers in our line of work. A list of highly recommended ones include the following: @@ -110,6 +107,46 @@ recommended ones include the following: - [PostgreSQL](https://marketplace.visualstudio.com/items?itemName=ckolkman.vscode-postgres) - syntax highlighting for PostgreSQL + + +## AI tools + +:::tip + +To learn more about how we use AI tools at Bitwarden, see our [AI](../../contributing/ai.md) +documentation. This page specifies how to configure AI tooling for development. + +::: + +### Claude Code + +We use Claude Code as our primary AI tool for development workflows. + +#### Installation + +Follow the installation instructions [here](https://code.claude.com/docs/en/quickstart). When +prompted, sign into the Anthropic Console via SSO and authenticate your local client. + +We also recommend integrating Claude Code into your IDE. See +[VS Code](https://code.claude.com/docs/en/vs-code) for setup instructions. + +#### Basic usage + +We recommend that you start with +[common workflows](https://code.claude.com/docs/en/common-workflows) and +[best practices](https://code.claude.com/docs/en/best-practices) from Anthropic for learning how to +start using Claude for development. + +### Bitwarden AI plugin marketplace + +Bitwarden maintains a curated set of AI plugins designed for our development workflows in our +[marketplace](https://github.com/bitwarden/ai-plugins). + +See the [`README`](https://github.com/bitwarden/ai-plugins/tree/main?tab=readme-ov-file#usage) in +the `ai-plugins` repo for installation and setup instructions. + + + ## Optional tools The following tools may be useful depending on your preferences or what you’re developing.