{"id":42208643,"url":"https://github.com/agentstation/pocket","last_synced_at":"2026-01-27T00:42:29.154Z","repository":{"id":305072178,"uuid":"1021803824","full_name":"agentstation/pocket","owner":"agentstation","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-18T04:03:55.000Z","size":69,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-18T07:19:14.716Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/agentstation.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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-07-18T01:32:03.000Z","updated_at":"2025-07-18T04:03:58.000Z","dependencies_parsed_at":"2025-07-18T07:19:42.603Z","dependency_job_id":"0b3dcce2-4ed5-48d0-9115-248f11b27e33","html_url":"https://github.com/agentstation/pocket","commit_stats":null,"previous_names":["agentstation/pocket"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/agentstation/pocket","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentstation%2Fpocket","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentstation%2Fpocket/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentstation%2Fpocket/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentstation%2Fpocket/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agentstation","download_url":"https://codeload.github.com/agentstation/pocket/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agentstation%2Fpocket/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28794012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T21:49:50.245Z","status":"ssl_error","status_checked_at":"2026-01-26T21:48:29.455Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-01-27T00:42:28.267Z","updated_at":"2026-01-27T00:42:29.148Z","avatar_url":"https://github.com/agentstation.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pocket\n\n[![CI Status](https://github.com/agentstation/pocket/actions/workflows/ci.yml/badge.svg)](https://github.com/agentstation/pocket/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nPocket is a CLI tool for executing LLM workflows defined as graphs. Write your workflows in YAML, extend with plugins in any language, and run them with a simple command.\n\n## What is Pocket?\n\nPocket executes workflows as directed graphs, where nodes make decisions and route data dynamically - perfect for LLM agents that need to think, act, and adapt based on their outputs.\n\n```mermaid\ngraph LR\n    Think[Think] --\u003e Decide{Decide Action}\n    Decide --\u003e|Research| Search[Search Web]\n    Decide --\u003e|Calculate| Math[Run Calculation]\n    Decide --\u003e|Complete| Done[Return Result]\n    Search --\u003e Think\n    Math --\u003e Think\n```\n\n## Installation\n\n### Quick Install (Recommended)\n\n```bash\n# macOS and Linux via Homebrew (pre-built binary)\nbrew install agentstation/tap/pocket\n\n# Or use our install script\ncurl -sSL https://raw.githubusercontent.com/agentstation/pocket/master/install.sh | bash\n```\n\n### Other Installation Methods\n\n\u003cdetails\u003e\n\u003csummary\u003eBuild from Source via Homebrew\u003c/summary\u003e\n\n```bash\n# Compile locally instead of using pre-built binary\nbrew install --build-from-source agentstation/tap/pocket\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eInstall via Go\u003c/summary\u003e\n\n```bash\ngo install github.com/agentstation/pocket/cmd/pocket@latest\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eDownload Pre-built Binaries\u003c/summary\u003e\n\nDownload the latest release for your platform from the [releases page](https://github.com/agentstation/pocket/releases/latest).\n\n```bash\n# Example for Linux x64\ncurl -L https://github.com/agentstation/pocket/releases/latest/download/pocket-linux-x86_64.tar.gz -o pocket.tar.gz\ntar -xzf pocket.tar.gz\nsudo mv pocket-linux-x86_64/pocket /usr/local/bin/\n```\n\nAvailable platforms:\n- macOS: `pocket-darwin-x86_64.tar.gz` (Intel), `pocket-darwin-arm64.tar.gz` (Apple Silicon)\n- Linux: `pocket-linux-x86_64.tar.gz`, `pocket-linux-arm64.tar.gz`, `pocket-linux-i386.tar.gz`\n- Windows: `pocket-windows-x86_64.zip`, `pocket-windows-i386.zip`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eVerify Installation\u003c/summary\u003e\n\n```bash\n# Check version\npocket version\n\n# Verify checksums (optional)\ncurl -L https://github.com/agentstation/pocket/releases/latest/download/checksums.txt -o checksums.txt\nsha256sum -c checksums.txt\n```\n\u003c/details\u003e\n\n## Quick Start\n\nCreate a workflow that thinks and acts:\n\n```yaml\n# agent.yaml\nname: simple-agent\nstart: think\n\nnodes:\n  - name: think\n    type: http\n    config:\n      url: \"https://api.openai.com/v1/chat/completions\"\n      method: POST\n      headers:\n        Authorization: \"Bearer ${OPENAI_API_KEY}\"\n      body:\n        model: \"gpt-4\"\n        messages:\n          - role: \"system\"\n            content: \"You are a helpful assistant. Respond with either SEARCH: \u003cquery\u003e or ANSWER: \u003cresponse\u003e\"\n          - role: \"user\"\n            content: \"{{.question}}\"\n            \n  - name: route\n    type: conditional\n    config:\n      conditions:\n        - if: '{{contains .choices[0].message.content \"SEARCH:\"}}'\n          then: search\n        - if: '{{contains .choices[0].message.content \"ANSWER:\"}}'\n          then: respond\n          \n  - name: search\n    type: http\n    config:\n      url: \"https://api.search.com/v1/search\"\n      params:\n        q: '{{.query}}'\n        \n  - name: respond\n    type: echo\n    config:\n      message: '{{.answer}}'\n\nconnections:\n  - from: think\n    to: route\n  - from: search\n    to: think  # Loop back with search results\n```\n\nRun it:\n\n```bash\npocket run agent.yaml --input '{\"question\": \"What is the weather in Tokyo?\"}'\n```\n\n## Why Pocket?\n\n### 🌐 Language Agnostic\n\nWrite workflows in YAML, extend with plugins in **any language**:\n- **Lua** - Quick scripts for custom logic\n- **WebAssembly** - Compile from Rust, Go, TypeScript, or any WASM-compatible language\n- **Native Go** - High-performance plugins\n\n### 🧠 Dynamic Routing\n\nUnlike linear pipelines, Pocket workflows make decisions:\n- Conditional branching based on data\n- Loops for agent think-act cycles  \n- Parallel execution for efficiency\n- Error handling with fallback paths\n\n### 🚀 Production Ready\n\nBuilt for real-world use:\n- Automatic retries with exponential backoff\n- Timeouts and cancellation\n- Comprehensive error handling\n- Observable with metrics and tracing\n\n### 📦 Zero Dependencies\n\nJust a single binary. No runtime required.\n\n## Key Features\n\n### Build LLM Agents That Think and Act\n\nCreate agents that can reason, search, use tools, and make decisions:\n\n```yaml\nnodes:\n  - name: agent-brain\n    type: lua\n    config:\n      script: |\n        -- Analyze the task and decide what to do\n        local task = input.task\n        if string.find(task, \"calculate\") then\n          return {action = \"calculator\", expression = task}\n        elseif string.find(task, \"search\") then\n          return {action = \"web_search\", query = task}\n        else\n          return {action = \"direct_answer\", task = task}\n        end\n```\n\n### Write Plugins in Any Language\n\n**Lua Script Plugin:**\n```lua\n-- sentiment.lua\nfunction exec(input)\n    local text = input.text:lower()\n    local positive = {\"good\", \"great\", \"excellent\", \"love\"}\n    local negative = {\"bad\", \"terrible\", \"hate\", \"awful\"}\n    \n    local score = 0\n    for _, word in ipairs(positive) do\n        if string.find(text, word) then score = score + 1 end\n    end\n    for _, word in ipairs(negative) do\n        if string.find(text, word) then score = score - 1 end\n    end\n    \n    return {\n        sentiment = score \u003e 0 and \"positive\" or score \u003c 0 and \"negative\" or \"neutral\",\n        score = score\n    }\nend\n```\n\n**WebAssembly Plugin (TypeScript):**\n```typescript\nexport function analyzeImage(input: ImageData): Analysis {\n    // Your image processing logic compiled to WASM\n    return { objects: detected, confidence: 0.95 };\n}\n```\n\n### Define Complex Workflows in Simple YAML\n\nPocket's YAML format is designed for clarity:\n\n```yaml\nname: data-pipeline\nstart: fetch\n\nnodes:\n  - name: fetch\n    type: parallel  # Fetch from multiple sources concurrently\n    config:\n      tasks:\n        - {type: http, config: {url: \"${API1}\"}}\n        - {type: http, config: {url: \"${API2}\"}}\n        \n  - name: merge\n    type: aggregate\n    config:\n      mode: combine\n      \n  - name: validate\n    type: validate\n    config:\n      schema:\n        type: object\n        required: [id, data]\n```\n\n### Production Features Built-In\n\n- **Retries**: `retry: {max_attempts: 3, delay: \"2s\"}`\n- **Timeouts**: `timeout: \"30s\"`\n- **Caching**: Built-in store with TTL\n- **Observability**: Metrics, traces, and structured logs\n\n## 📚 Documentation\n\n- **[Getting Started Guide](docs/cli/getting-started.md)** - Build your first workflow\n- **[Workflow Examples](docs/workflows/)** - Real-world patterns and use cases\n- **[Plugin Development](docs/cli/plugins.md)** - Extend Pocket with custom nodes\n- **[Full Documentation](docs/README.md)** - All guides and references\n\n## Examples\n\n### LLM Agent with Tools\n\n```yaml\nname: research-agent\nstart: think\n\nnodes:\n  - name: think\n    type: llm  # Uses OpenAI, Anthropic, or local models\n    config:\n      prompt: |\n        You have access to: calculator, web_search, file_reader\n        User query: {{.query}}\n        Respond with the tool to use and parameters.\n        \n  - name: use-tool\n    type: router\n    config:\n      routes:\n        calculator: calc-node\n        web_search: search-node\n        file_reader: read-node\n```\n\n### Data Processing Pipeline\n\n```yaml\nname: etl-pipeline\nstart: extract\n\nnodes:\n  - name: extract\n    type: file\n    config:\n      path: \"data/*.json\"\n      \n  - name: transform\n    type: transform\n    config:\n      jq: 'map(select(.active) | {id, name, value: .price * 1.1})'\n      \n  - name: load\n    type: http\n    config:\n      url: \"${WAREHOUSE_API}\"\n      method: POST\n```\n\n[→ More Examples](docs/workflows/)\n\n## Plugins\n\nExtend Pocket with plugins:\n\n```bash\n# Install a plugin\npocket plugin install github.com/example/pocket-redis\n\n# Use in your workflow\nnodes:\n  - name: cache-result\n    type: redis-set  # From the plugin\n    config:\n      key: \"result:{{.id}}\"\n      value: \"{{.data}}\"\n```\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines.\n\n```bash\n# Run tests\ngo test -race ./...\n\n# Build\nmake build\n\n# Run benchmarks\nmake bench\n```\n\n## Using as a Go Library\n\nWhile Pocket is designed as a CLI tool, it can also be embedded in Go applications:\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"github.com/agentstation/pocket\"\n)\n\nfunc main() {\n    // Create nodes\n    process := pocket.NewNode[Input, Output](\"process\",\n        pocket.Steps{\n            Exec: func(ctx context.Context, input any) (any, error) {\n                // Your logic here\n                return processData(input.(Input))\n            },\n        },\n    )\n    \n    // Build and run workflow\n    graph := pocket.NewGraph(process, pocket.NewStore())\n    result, _ := graph.Run(context.Background(), myInput)\n}\n```\n\n[→ Go Library Documentation](docs/library/)\n\n## Development\n\n### Prerequisites\n\n- Go 1.21+\n- Make (optional)\n\n### Building from Source\n\n```bash\ngit clone https://github.com/agentstation/pocket.git\ncd pocket\ngo build -o pocket cmd/pocket/main.go\n```\n\n### Architecture\n\nPocket uses a three-phase execution model:\n\n1. **Prep** - Validate input and prepare data\n2. **Exec** - Execute core logic (pure functions)\n3. **Post** - Handle results and routing decisions\n\nThis ensures predictable execution and easy testing.\n\n### Go-Specific Information\n\n[![Go Reference](https://pkg.go.dev/badge/github.com/agentstation/pocket.svg)](https://pkg.go.dev/github.com/agentstation/pocket)\n[![Go Report Card](https://goreportcard.com/badge/github.com/agentstation/pocket)](https://goreportcard.com/report/github.com/agentstation/pocket)\n[![codecov](https://codecov.io/gh/agentstation/pocket/graph/badge.svg?token=3EQVJCCSHN)](https://codecov.io/gh/agentstation/pocket)\n\n## License\n\nMIT - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\nBuilt with ❤️ by [AgentStation](https://agentstation.ai) for the LLM agent community.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentstation%2Fpocket","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagentstation%2Fpocket","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagentstation%2Fpocket/lists"}