{"id":28882252,"url":"https://github.com/onkernel/cu-playwright-ts","last_synced_at":"2025-09-07T11:44:57.768Z","repository":{"id":300070719,"uuid":"1003913105","full_name":"onkernel/cu-playwright-ts","owner":"onkernel","description":"Maps Claude Computer Use to Playwright","archived":false,"fork":false,"pushed_at":"2025-07-09T00:50:57.000Z","size":53,"stargazers_count":2,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-09T01:46:56.676Z","etag":null,"topics":["agentic-ai","llm","playwright"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onkernel.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-17T20:37:56.000Z","updated_at":"2025-07-09T00:51:00.000Z","dependencies_parsed_at":"2025-06-19T18:50:31.585Z","dependency_job_id":"ce9471da-880f-4058-81ce-f612073ced22","html_url":"https://github.com/onkernel/cu-playwright-ts","commit_stats":null,"previous_names":["onkernel/cu-playwright-ts"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/onkernel/cu-playwright-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onkernel%2Fcu-playwright-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onkernel%2Fcu-playwright-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onkernel%2Fcu-playwright-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onkernel%2Fcu-playwright-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onkernel","download_url":"https://codeload.github.com/onkernel/cu-playwright-ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onkernel%2Fcu-playwright-ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274032056,"owners_count":25210784,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","llm","playwright"],"created_at":"2025-06-20T21:01:19.569Z","updated_at":"2025-09-07T11:44:57.760Z","avatar_url":"https://github.com/onkernel.png","language":"TypeScript","readme":"# Computer Use Playwright SDK\n\nA TypeScript SDK that combines Anthropic's Computer Use capabilities with Playwright for browser automation tasks. This SDK provides a clean, type-safe interface for automating browser interactions using Claude's computer use abilities.\n\n## Features\n\n- 🤖 **Simple API**: Single `ComputerUseAgent` class for all computer use tasks\n- 🔄 **Dual Response Types**: Support for both text and structured (JSON) responses\n- 🛡️ **Type Safety**: Full TypeScript support with Zod schema validation\n- ⚡ **Optimized**: Clean error handling and robust JSON parsing\n- 🎯 **Focused**: Clean API surface with sensible defaults\n\n## Installation\n\n```bash\nnpm install @onkernel/cu-playwright\n# or\nyarn add @onkernel/cu-playwright\n# or\nbun add @onkernel/cu-playwright\n```\n\n## Quick Start\n\n```typescript\nimport { chromium } from 'playwright';\nimport { ComputerUseAgent } from '@onkernel/cu-playwright';\n\nconst browser = await chromium.launch({ headless: false });\nconst page = await browser.newPage();\n\n// Navigate to Hacker News manually first\nawait page.goto(\"https://news.ycombinator.com/\");\n\nconst agent = new ComputerUseAgent({\n  apiKey: process.env.ANTHROPIC_API_KEY!,\n  page,\n});\n\n// Simple text response\nconst answer = await agent.execute('Tell me the title of the top story');\nconsole.log(answer);\n\nawait browser.close();\n```\n\n## API Reference\n\n### `ComputerUseAgent`\n\nThe main class for computer use automation.\n\n#### Constructor\n\n```typescript\nnew ComputerUseAgent(options: {\n  apiKey: string;\n  page: Page;\n  model?: string;\n})\n```\n\n**Parameters:**\n- `apiKey` (string): Your Anthropic API key. Get one from [Anthropic Console](https://console.anthropic.com/)\n- `page` (Page): Playwright page instance to control\n- `model` (string, optional): Anthropic model to use. Defaults to `'claude-sonnet-4-20250514'`\n\n**Supported Models:**\nSee [Anthropic's Computer Use documentation](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/computer-use-tool#model-compatibility) for the latest model compatibility.\n\n#### `execute()` Method\n\n```typescript\nasync execute\u003cT = string\u003e(\n  query: string,\n  schema?: z.ZodSchema\u003cT\u003e,\n  options?: {\n    systemPromptSuffix?: string;\n    thinkingBudget?: number;\n  }\n): Promise\u003cT\u003e\n```\n\n**Parameters:**\n\n- **`query`** (string): The task description for Claude to execute\n  \n- **`schema`** (ZodSchema, optional): Zod schema for structured responses. When provided, the response will be validated against this schema\n  \n- **`options`** (object, optional):\n  - **`systemPromptSuffix`** (string): Additional instructions appended to the system prompt\n  - **`thinkingBudget`** (number): Token budget for Claude's internal reasoning process. Default: `1024`. See [Extended Thinking documentation](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking) for details\n\n**Returns:** \n- `Promise\u003cT\u003e`: When `schema` is provided, returns validated data of type `T`\n- `Promise\u003cstring\u003e`: When no `schema` is provided, returns the text response\n\n## Usage Examples\n\n### Text Response\n\n```typescript\nimport { ComputerUseAgent } from '@onkernel/cu-playwright-ts';\n\n// Navigate to the target page first\nawait page.goto(\"https://news.ycombinator.com/\");\n\nconst agent = new ComputerUseAgent({\n  apiKey: process.env.ANTHROPIC_API_KEY!,\n  page,\n});\n\nconst result = await agent.execute(\n  'Tell me the title of the top story on this page'\n);\nconsole.log(result); // \"Title of the top story\"\n```\n\n### Structured Response with Zod\n\n```typescript\nimport { z } from 'zod';\nimport { ComputerUseAgent } from '@onkernel/cu-playwright-ts';\n\nconst agent = new ComputerUseAgent({\n  apiKey: process.env.ANTHROPIC_API_KEY!,\n  page,\n});\n\nconst HackerNewsStory = z.object({\n  title: z.string(),\n  points: z.number(),\n  author: z.string(),\n  comments: z.number(),\n  url: z.string().optional(),\n});\n\nconst stories = await agent.execute(\n  'Get the top 5 Hacker News stories with their details',\n  z.array(HackerNewsStory).max(5)\n);\n\nconsole.log(stories);\n// [\n//   {\n//     title: \"Example Story\",\n//     points: 150,\n//     author: \"user123\",\n//     comments: 42,\n//     url: \"https://example.com\"\n//   },\n//   ...\n// ]\n```\n\n### Advanced Options\n\n```typescript\nconst result = await agent.execute(\n  'Complex task requiring more thinking',\n  undefined, // No schema for text response\n  {\n    systemPromptSuffix: 'Be extra careful with form submissions.',\n    thinkingBudget: 4096, // More thinking tokens for complex tasks\n  }\n);\n```\n\n## Environment Setup\n\n1. **Anthropic API Key**: Set your API key as an environment variable:\n   ```bash\n   export ANTHROPIC_API_KEY=your_api_key_here\n   ```\n\n2. **Playwright**: Install Playwright and browser dependencies:\n   ```bash\n   npx playwright install\n   ```\n\n## Computer Use Parameters\n\nThis SDK leverages Anthropic's Computer Use API with the following key parameters:\n\n### Model Selection\n- **Claude 3.5 Sonnet**: Best balance of speed and capability for most tasks\n- **Claude 4 Models**: Enhanced reasoning with extended thinking capabilities\n- **Claude 3.7 Sonnet**: Advanced reasoning with thinking transparency\n\n### Thinking Budget\nThe `thinkingBudget` parameter controls Claude's internal reasoning process:\n- **1024 tokens** (default): Suitable for simple tasks\n- **4096+ tokens**: Better for complex reasoning tasks\n- **16k+ tokens**: Recommended for highly complex multi-step operations\n\nSee [Anthropic's Extended Thinking guide](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking#working-with-thinking-budgets) for optimization tips.\n\n## Error Handling\n\nThe SDK includes built-in error handling:\n\n```typescript\ntry {\n  const result = await agent.execute('Your task here');\n  console.log(result);\n} catch (error) {\n  if (error.message.includes('No response received')) {\n    console.log('Agent did not receive a response from Claude');\n  } else {\n    console.log('Other error:', error.message);\n  }\n}\n```\n\n## Best Practices\n\n1. **Use specific, clear instructions**: \"Click the red 'Submit' button\" vs \"click submit\"\n\n2. **For complex tasks, break them down**: Use step-by-step instructions in your query\n\n3. **Optimize thinking budget**: Start with default (1024) and increase for complex tasks\n\n4. **Handle errors gracefully**: Implement proper error handling for production use\n\n5. **Use structured responses**: When you need specific data format, use Zod schemas\n\n6. **Test in headless: false**: During development, run with visible browser to debug\n\n## Security Considerations\n\n⚠️ **Important**: Computer use can interact with any visible application. Always:\n\n- Run in isolated environments (containers/VMs) for production\n- Avoid providing access to sensitive accounts or data\n- Review Claude's actions in logs before production deployment\n- Use allowlisted domains when possible\n\nSee [Anthropic's Computer Use Security Guide](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/computer-use-tool#security-considerations) for detailed security recommendations.\n\n## Requirements\n\n- Node.js 18+\n- TypeScript 5+\n- Playwright 1.52+\n- Anthropic API key\n\n## Related Resources\n\n- [Anthropic Computer Use Documentation](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/computer-use-tool)\n- [Extended Thinking Guide](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking)\n- [Playwright Documentation](https://playwright.dev/)\n- [Zod Documentation](https://zod.dev/)\n\n## License\n\nSee [License](./LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonkernel%2Fcu-playwright-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonkernel%2Fcu-playwright-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonkernel%2Fcu-playwright-ts/lists"}