{"id":42894997,"url":"https://github.com/stigmer/stigmer","last_synced_at":"2026-05-02T10:04:49.264Z","repository":{"id":333213510,"uuid":"1136576010","full_name":"stigmer/stigmer","owner":"stigmer","description":"Build AI agents and workflows with zero infrastructure","archived":false,"fork":false,"pushed_at":"2026-05-02T05:59:36.000Z","size":289804,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-02T06:16:26.478Z","etag":null,"topics":["agents","ai","automation","golang","mcp","open-source","python","sqlite","workflow"],"latest_commit_sha":null,"homepage":"https://stigmer.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stigmer.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-17T23:54:27.000Z","updated_at":"2026-05-02T05:59:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/stigmer/stigmer","commit_stats":null,"previous_names":["stigmer/stigmer"],"tags_count":297,"template":false,"template_full_name":null,"purl":"pkg:github/stigmer/stigmer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stigmer%2Fstigmer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stigmer%2Fstigmer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stigmer%2Fstigmer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stigmer%2Fstigmer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stigmer","download_url":"https://codeload.github.com/stigmer/stigmer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stigmer%2Fstigmer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32530178,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"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":["agents","ai","automation","golang","mcp","open-source","python","sqlite","workflow"],"created_at":"2026-01-30T15:05:50.031Z","updated_at":"2026-05-02T10:04:49.248Z","avatar_url":"https://github.com/stigmer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Stigmer\n\n**Build AI agents and workflows with zero infrastructure.**\n\nStigmer is an open-source agentic automation platform. Run it locally with SQLite for development, or connect to Stigmer Cloud for production. Bring your own LLM — Anthropic, OpenAI, or Ollama. Same CLI, same SDK, same resource definitions — your choice of backend.\n\n## Quick Start\n\n### 1. Install\n\n```bash\n# Homebrew (macOS/Linux)\nbrew install stigmer/tap/stigmer\n\n# Or from source\ngit clone https://github.com/stigmer/stigmer.git\ncd stigmer \u0026\u0026 make release-local\n\n# Or via shell script\ncurl -fsSL https://raw.githubusercontent.com/stigmer/stigmer/main/scripts/install.sh | bash\n```\n\nThis installs a single self-contained `stigmer` binary that embeds all required components.\n\n### 2. Configure LLM Provider\n\nStigmer agents need an LLM to generate responses. You can pre-configure one before starting the server, or let the interactive setup guide you on first run.\n\n**Option A: Anthropic (recommended for best quality)**\n\n```bash\nexport ANTHROPIC_API_KEY=sk-ant-...\n```\n\n**Option B: OpenAI**\n\n```bash\nexport OPENAI_API_KEY=sk-...\n```\n\n**Option C: Ollama (free, local, offline)**\n\n```bash\nbrew install ollama\nollama serve\nollama pull qwen2.5-coder:7b\n```\n\nIf you skip this step, `stigmer server` will prompt you to choose a provider interactively.\n\n### 3. Start the Server\n\n```bash\nstigmer server\n```\n\nOn first run, this prompts you to choose an LLM provider, auto-downloads Temporal, starts all services, and is ready on `localhost:7234`.\n\n### 4. Deploy and Run an Agent\n\n```bash\n# Deploy from a YAML file\nstigmer apply -f agent.yaml\n\n# Execute\nstigmer run support-bot \"How do I reset my password?\"\n```\n\n### Managing the Server\n\n```bash\nstigmer server status   # check if running\nstigmer server stop     # stop all services\nstigmer server          # start again\nstigmer server setup    # reconfigure LLM provider\nstigmer server reset    # stop and remove all data (keeps config)\n```\n\n## Core Concepts\n\n### Agents\n\nAn agent has instructions, optional MCP servers for tool access, and optional model configuration.\n\n```yaml\napiVersion: agentic.stigmer.ai/v1\nkind: Agent\nmetadata:\n  name: support-bot\nspec:\n  instructions: |\n    You are a helpful customer support agent.\n    Answer questions politely and accurately.\n    Check GitHub issues for known problems.\n  mcpServers:\n    - github\n    - filesystem\n```\n\n```bash\nstigmer apply -f agent.yaml\nstigmer run support-bot \"What's the status of issue #42?\"\n```\n\n### Workflows\n\nMulti-step automations that chain HTTP calls, agent calls, variable assignments, conditionals, and loops. Workflows follow the [CNCF Serverless Workflow](https://serverlessworkflow.io/) DSL.\n\n```yaml\napiVersion: agentic.stigmer.ai/v1\nkind: Workflow\nmetadata:\n  name: hello-world\nspec:\n  description: A minimal workflow\n  document:\n    dsl: \"1.0.0\"\n    namespace: examples\n    name: hello-world\n    version: \"1.0.0\"\n  tasks:\n    - name: set-greeting\n      kind: set_vars\n      task_config:\n        variables:\n          greeting: \"Hello, World!\"\n          timestamp: \"${now()}\"\n      export:\n        as: \"${.}\"\n```\n\nTasks support `kind: set_vars`, `kind: http_call`, `kind: agent_call`, `kind: wait`, and control flow via `flow.then`. See [examples/workflows/](examples/workflows/) for more complex patterns including multi-agent orchestration and conditional branching.\n\n```bash\nstigmer apply -f workflow.yaml\nstigmer run hello-world\n```\n\n### Skills\n\nVersioned knowledge artifacts (instructions + reference material) that agents can use. A skill is a directory with a `SKILL.md` file containing YAML frontmatter:\n\n```\nmy-skill/\n  SKILL.md          # Required: interface definition with YAML frontmatter\n  tool.sh           # Optional: tool implementation\n  README.md         # Optional: documentation\n```\n\n```bash\nstigmer push                          # push skill from current directory\nstigmer draft skill --name my-skill   # scaffold a new skill\n```\n\n### MCP Servers\n\nStigmer uses the [Model Context Protocol](https://modelcontextprotocol.io) to give agents tool access. Agents can use any STDIO-based MCP server — npm packages (npx), Python packages (uvx), Go modules (go run), or Docker images.\n\nStigmer also ships its own MCP server that exposes platform resources to AI-powered IDEs:\n\n```bash\nstigmer mcp-server\n```\n\nSee [mcp-server/README.md](mcp-server/README.md) for IDE configuration (Cursor, Claude Desktop, VS Code, Windsurf).\n\n## Go SDK\n\nDefine agents and workflows programmatically using a Pulumi-aligned struct args API.\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"log\"\n\n    \"github.com/stigmer/stigmer/sdk/go/agent\"\n    \"github.com/stigmer/stigmer/sdk/go/stigmer\"\n)\n\nfunc main() {\n    err := stigmer.Run(func(ctx *stigmer.Context) error {\n        a, err := agent.New(ctx, \"code-reviewer\", \u0026agent.AgentArgs{\n            Instructions: \"Review code for best practices and security issues\",\n        })\n        if err != nil {\n            return err\n        }\n        fmt.Printf(\"Created agent: %s\\n\", a.Name)\n        return nil\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n}\n```\n\nSee [sdk/go/README.md](sdk/go/README.md) for the full SDK reference, workflow builders, and more examples in [sdk/go/examples/](sdk/go/examples/).\n\n## CLI Reference\n\n| Command | Description |\n|---------|-------------|\n| `stigmer run \u003cname\u003e [prompt]` | Execute an agent or workflow |\n| `stigmer apply -f \u003cfile\u003e` | Create or update resources from YAML |\n| `stigmer get \u003ckind\u003e \u003cname\u003e` | Get a resource |\n| `stigmer list \u003ckind\u003e` | List resources |\n| `stigmer delete \u003ckind\u003e \u003cname\u003e` | Delete a resource |\n| `stigmer search \u003cquery\u003e` | Full-text search across resources |\n| `stigmer draft \u003ckind\u003e` | Scaffold a new resource |\n| `stigmer push` | Push a skill artifact |\n| `stigmer download \u003ckind\u003e \u003cname\u003e` | Download a resource artifact |\n| `stigmer validate -f \u003cfile\u003e` | Validate a resource definition |\n| `stigmer server` | Start/stop/status/setup/reset for local server |\n| `stigmer mcp-server` | Start the Stigmer MCP server |\n| `stigmer backend` | Switch between local and cloud backends |\n| `stigmer config` | Manage CLI configuration |\n\n## Local vs Cloud\n\n| | Local Mode (Open Source) | Cloud Mode (Stigmer Cloud) |\n|---|---|---|\n| **Start with** | `stigmer server` | `stigmer backend set cloud` |\n| **Storage** | SQLite (`~/.stigmer/stigmer.db`) | Distributed (managed) |\n| **Orchestration** | Temporal (auto-managed) | Temporal (managed) |\n| **Users** | Single implicit user | Organizations, teams, IAM |\n| **LLM** | Anthropic, OpenAI, or Ollama (user's choice) | Configurable |\n| **Best for** | Development, personal projects, air-gapped environments | Team collaboration, production, governance |\n\nResource definitions are portable across both modes. The CLI talks to the same gRPC service interfaces regardless of backend.\n\n### LLM Configuration\n\nOn first run, `stigmer server` guides you through an interactive setup to choose your LLM provider. The chosen provider and API key are saved to `~/.stigmer/config.yaml`.\n\n**Supported providers:**\n\n| Provider | Model (default) | Requires |\n|----------|----------------|----------|\n| Anthropic | `claude-sonnet-4.5` | `ANTHROPIC_API_KEY` env var or API key in config |\n| OpenAI | `gpt-4` | `OPENAI_API_KEY` env var or API key in config |\n| Ollama | `qwen2.5-coder:7b` | Ollama installed and running locally |\n\n**Config file example** (`~/.stigmer/config.yaml`):\n\n```yaml\nbackend:\n  local:\n    llm:\n      provider: anthropic\n      model: claude-sonnet-4.5\n```\n\n**Environment variables** (take precedence over config file):\n\n```bash\nexport STIGMER_LLM_PROVIDER=anthropic\nexport ANTHROPIC_API_KEY=sk-ant-...\n```\n\n### Changing Your LLM Provider\n\nRe-run the interactive setup:\n\n```bash\nstigmer server setup\n```\n\nOr set the provider directly:\n\n```bash\nstigmer config set llm.provider anthropic    # switch to Anthropic\nstigmer config set llm.provider openai       # switch to OpenAI\nstigmer config set llm.provider ollama       # switch to Ollama\n```\n\nAfter changing the provider, restart the server:\n\n```bash\nstigmer server stop \u0026\u0026 stigmer server\n```\n\n## Architecture\n\nStigmer is a single binary (BusyBox pattern) that embeds all required services:\n\n```\n┌──────────────────────────────────────────────────────┐\n│                  stigmer CLI (Go)                     │\n│              (client-apps/cli/)                       │\n└────────────────────┬─────────────────────────────────┘\n                     │ gRPC (localhost:7234)\n┌────────────────────▼─────────────────────────────────┐\n│            stigmer-server (Go)                        │\n│        (backend/services/stigmer-server/)             │\n│                                                       │\n│  Controllers: Agent, Workflow, Skill, MCP Server      │\n│  Storage: SQLite via modernc.org/sqlite (pure Go)     │\n└────────────────────┬─────────────────────────────────┘\n                     │ Temporal Client\n┌────────────────────▼─────────────────────────────────┐\n│            Temporal (auto-managed)                     │\n└───────────┬───────────────────────┬──────────────────┘\n┌───────────▼──────────┐  ┌────────▼──────────────────┐\n│  agent-runner        │  │  workflow-runner           │\n│  (Python)            │  │  (Go)                      │\n│  Graphton agent      │  │  CNCF Serverless Workflow  │\n│  execution           │  │  execution                 │\n└──────────────────────┘  └───────────────────────────┘\n```\n\n**Components:**\n\n- **stigmer CLI** — User-facing command-line interface with backend abstraction (local daemon vs cloud). Location: `client-apps/cli/`\n- **stigmer-server** — Go gRPC API server with SQLite storage, protobuf validation, and full-text search (FTS5). Location: `backend/services/stigmer-server/`\n- **agent-runner** — Python Temporal worker for AI agent execution via the Graphton framework. Location: `backend/services/agent-runner/`\n- **workflow-runner** — Go Temporal worker for CNCF Serverless Workflow execution with Claim Check and Continue-As-New patterns. Location: `backend/services/workflow-runner/`\n- **Go SDK** — Pulumi-aligned SDK for defining agents and workflows programmatically. Location: `sdk/go/`\n- **MCP Server** — Stateless MCP gateway bridging AI IDEs to stigmer-server via gRPC. Location: `mcp-server/`\n- **Proto APIs** — gRPC service definitions that serve as the contract between CLI and backends. Location: `apis/`\n\n## Development\n\n### Prerequisites\n\n- Go 1.25 or later\n- Python 3.11+ with [Poetry](https://python-poetry.org/) (for agent-runner)\n- Git, Make\n\n### Building from Source\n\n```bash\ngit clone https://github.com/stigmer/stigmer.git\ncd stigmer\n\n# Install all dependencies\nmake setup\n\n# Build the CLI (outputs bin/stigmer)\nmake build\n\n# Run tests\nmake test\n```\n\n### Proto Generation\n\n```bash\ncd apis\nmake build         # generate Go + Python stubs\nmake lint          # lint proto files\nmake fmt           # format proto files\n```\n\nGenerated stubs go to `apis/stubs/` (excluded from version control). See [apis/README.md](apis/README.md) for details.\n\n### Releases\n\n```bash\nmake release bump=patch   # create a release tag (triggers GoReleaser via GitHub Actions)\nmake protos-release       # publish protos to Buf separately\n```\n\nSee [Distribution Guide](docs/guides/distribution.md) for the full packaging and release process.\n\n## Troubleshooting\n\n**Server won't start:**\n\n```bash\nstigmer server status              # check if already running\nstigmer server stop \u0026\u0026 sleep 2 \u0026\u0026 stigmer server   # restart cleanly\n```\n\n**Check logs:**\n\n```bash\nstigmer server logs\n```\n\n**Reset all local data:**\n\n```bash\nstigmer server reset    # stops services, removes data, keeps config\nstigmer server          # recreates everything on first run\n```\n\nTo also remove configuration (API keys, LLM preferences):\n\n```bash\nstigmer server reset --include-config\n```\n\n## Documentation\n\n- [Full Documentation Index](docs/README.md)\n- [Local Mode Guide](docs/getting-started/local-mode.md)\n- [Architecture](docs/architecture/) — [Temporal Integration](docs/architecture/temporal-integration.md), [Open Core Model](docs/architecture/open-core-model.md), [Packaging Flow](docs/architecture/packaging-flow.md)\n- [Guides](docs/guides/) — [Environment Variables](docs/guides/environment-variables.md), [Using MCP Servers](docs/guides/using-mcp-servers.md), [Uploading Skills](docs/guides/uploading-skills.md)\n- [Examples](examples/) — Sample agents, workflows, and skills\n\n## Contributing\n\nWe welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n- [GitHub Issues](https://github.com/stigmer/stigmer/issues) — Bug reports and feature requests\n- [Discord](https://discord.gg/stigmer) — Community chat\n\n## License\n\nApache License 2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstigmer%2Fstigmer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstigmer%2Fstigmer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstigmer%2Fstigmer/lists"}