diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..d9dabfefd
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,132 @@
+# Contributing to agent-browser
+
+Thanks for your interest in contributing to agent-browser! This guide will help you get set up and submit your first PR.
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js** >= 20
+- **pnpm** (package manager)
+- **Rust** (optional, for native CLI binary — install via [rustup.rs](https://rustup.rs))
+
+### Getting Started
+
+```bash
+# Clone the repository
+git clone https://github.com/dextonai/agent-browser.git
+cd agent-browser
+
+# Install dependencies
+pnpm install
+
+# Build the TypeScript source
+pnpm build
+
+# (Optional) Build the native Rust CLI for maximum performance
+pnpm build:native
+```
+
+### Running Locally
+
+```bash
+# Start the daemon in development mode (with hot reload)
+pnpm dev
+
+# Or run the built version
+pnpm start
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+pnpm test
+
+# Run tests in watch mode during development
+pnpm test:watch
+```
+
+## Coding Style
+
+This project uses **Prettier** for code formatting and **TypeScript** for type safety.
+
+```bash
+# Check formatting
+pnpm format:check
+
+# Auto-fix formatting
+pnpm format
+
+# Type-check without emitting
+pnpm typecheck
+```
+
+### Style Guidelines
+
+- Use TypeScript for all source files in `src/`
+- Follow the existing code patterns and naming conventions
+- Keep functions focused and well-documented
+- Use descriptive variable names
+- Add JSDoc comments for public APIs
+
+## Project Structure
+
+```
+agent-browser/
+├── src/           # TypeScript source (daemon, commands, providers)
+├── cli/           # Rust CLI source (native binary)
+├── bin/           # CLI entry point and native binaries
+├── dist/          # Compiled output
+├── test/          # Test files (Vitest)
+├── docs/          # Documentation
+├── skills/        # AI agent skill definitions
+├── scripts/       # Build and utility scripts
+└── docker/        # Docker build configs
+```
+
+## Submitting a Pull Request
+
+1. **Fork** the repository and create a feature branch:
+   ```bash
+   git checkout -b feat/your-feature-name
+   ```
+
+2. **Make your changes** and ensure:
+   - Code compiles: `pnpm build`
+   - Tests pass: `pnpm test`
+   - Formatting is correct: `pnpm format:check`
+   - Types are valid: `pnpm typecheck`
+
+3. **Add a changeset** if your change affects the public API or behavior:
+   ```bash
+   pnpm changeset
+   ```
+   Follow the prompts to describe your change and select the semver bump type.
+
+4. **Commit** with a clear message following [Conventional Commits](https://www.conventionalcommits.org/):
+   ```
+   feat: add new snapshot filter option
+   fix: resolve timeout issue with CDP connections
+   docs: update README with new examples
+   ```
+
+5. **Push** and open a Pull Request against `main`.
+
+## Types of Contributions
+
+- **Bug fixes** — Fix issues and add regression tests
+- **Features** — New commands, providers, or integrations
+- **Documentation** — Improve README, add examples, fix typos
+- **Tests** — Increase test coverage
+- **Performance** — Optimize the daemon or CLI
+
+## Need Help?
+
+- Check existing [issues](https://github.com/dextonai/agent-browser/issues) for context
+- Open a new issue if you find a bug or have a feature request
+- Read the [README](./README.md) for full command reference
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [Apache-2.0 License](./LICENSE).
diff --git a/README.md b/README.md
index 7b0dfba9a..543cfd975 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,9 @@
 # agent-browser
 
+[![Build Status](https://img.shields.io/github/actions/workflow/status/dextonai/agent-browser/ci.yml?branch=main&style=flat-square)](https://github.com/dextonai/agent-browser/actions)
+[![npm version](https://img.shields.io/npm/v/agent-browser?style=flat-square)](https://www.npmjs.com/package/agent-browser)
+[![License](https://img.shields.io/github/license/dextonai/agent-browser?style=flat-square)](./LICENSE)
+
 Headless browser automation CLI for AI agents. Fast Rust CLI with Node.js fallback.
 
 ## Installation
@@ -1102,6 +1106,10 @@ When enabled, agent-browser connects to a Kernel cloud session instead of launch
 
 Get your API key from the [Kernel Dashboard](https://dashboard.onkernel.com).
 
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions, coding style guidelines, and how to submit a PR.
+
 ## License
 
 Apache-2.0