README
¶
This repository has moved to Gitea. Active development continues at gitea.herbhall.net/samverk/samverk. This GitHub repository is a read-only archive. Issues and PRs are disabled.
Samverk
Samverk -- Old Norse/Icelandic: "cooperative work" (sam = together, verk = work/deed)
Your project keeps building while you're at work, with the kids, or asleep. You just need a few minutes a day to keep it moving.
Samverk is an async background development engine. It coordinates AI agents to keep your project moving forward while you live your life -- then surfaces a digest when you have a few minutes to check in.
Why
Every AI dev tool today is synchronous. You sit at your keyboard, prompt, wait, review, repeat. That works if coding is your full-time job. It doesn't work if you have 10-15 minutes between obligations.
Solo dev projects typically take 5-10 years or never ship at all. Not because of lack of skill -- because of lack of time and momentum. Life interrupts, the project goes cold, restarting is psychologically hard, and there's no one to hand work off to.
Samverk's metric isn't faster responses or cheaper API calls. It's: did the project ship.
A project that would take a solo dev 5-10 years (or never ship) ships in 12-18 months.
How It Works
- You describe what you want to build
- Samverk's agent hierarchy researches, plans, builds, and validates -- continuously
- When you have a few minutes, you check in from any device
- Samverk shows you what's done, what's in progress, and what needs your input
- You provide direction, answer questions, approve decisions
- You close the app. Samverk keeps working.
Architecture
Agents are organized in a hybrid local/cloud model:
Cloud (Claude, GPT-4, etc.) Complex reasoning, orchestration, QC arbitration
Mid-tier (API or large local) Task decomposition, planning
Local (containerized, GPU) Code generation, testing, formatting, docs
Multi-model by default. Provider failover on credit exhaustion. Different models catch different bugs -- diversity improves quality.
See Architecture for full detail.
Key Differentiators
- Async-first -- works while you're away, not while you're watching
- Check-in model -- 5-15 minute sessions from any device
- Hybrid local/cloud -- local handles volume, cloud handles complexity
- Multi-model failover -- cost management and quality diversity in one feature
- Parallel QC -- validation built into the hierarchy, not bolted on
- No lock-in -- every hardware tier produces a working result
Target Users
The hobbyist developer with a full life. Has a job, a family, genuine programming interest, and an idea that keeps dying from loss of momentum.
Not targeting: enterprise teams, AI engineers, or full-time developers who can sit with tools all day.
Documentation
- Concept and Problem Space
- Architecture
- Tech Stack
- Communication Protocol
- Dispatcher Design
- Autonomy Model
- User Profile
- System Requirements
- Competitive Landscape
- Cost Model
- User Interface
- Open Questions
- Naming and Background
- Decision Records
Status
Phase 2 complete. Core infrastructure operational with MCP server, check-in digest, and end-to-end validation (GO decision). 118 tests passing across 11 packages.
Phase 1 delivered: dispatcher routing, frontmatter parser, profile store, SQLite persistence, GitHub and Gitea forge adapters, Ollama provider, autonomy policy engine.
Phase 2 delivered: HTTP server with health endpoint, MCP handler (get_digest + get_cost_summary tools via Streamable HTTP), cost tracking adapter, check-in digest prototype, label taxonomy (47 labels), front-end agent system prompt design.
Next: Phase 3 -- wire remaining forge ops as MCP tools, session recording, Claude Desktop integration, authentication middleware, web dashboard.
Related Projects
- Subnetree -- Network monitoring tool; intended dogfood project to be built using Samverk
- Devkit -- Windows development environment setup; the infrastructure layer Samverk runs on top of
License
TBD -- likely BSL 1.1 / Apache 2.0 dual license (consistent with Subnetree approach)
Started: February 2026 | Author: Herb Hall
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
samverk
command
|
|
|
internal
|
|
|
agent
Package agent provides the agent runtime pool and runner for processing tasks as goroutines with session lifecycle management and cost recording.
|
Package agent provides the agent runtime pool and runner for processing tasks as goroutines with session lifecycle management and cost recording. |
|
api
Package api provides REST API handlers for the web dashboard.
|
Package api provides REST API handlers for the web dashboard. |
|
audit
Package audit provides health-check and freshness auditing for AI providers.
|
Package audit provides health-check and freshness auditing for AI providers. |
|
autonomy
Package autonomy implements the three-tier trust model for agent action evaluation.
|
Package autonomy implements the three-tier trust model for agent action evaluation. |
|
cost
Package cost provides token tracking, budget management, and cost attribution.
|
Package cost provides token tracking, budget management, and cost attribution. |
|
digest
Package digest assembles check-in digests from forge issues.
|
Package digest assembles check-in digests from forge issues. |
|
dispatcher
Package dispatcher watches the issue tracker, routes tasks to agents, and manages dependencies.
|
Package dispatcher watches the issue tracker, routes tasks to agents, and manages dependencies. |
|
forge
Package forge provides the IssueTracker interface and implementations for GitHub, Gitea, and GitLab.
|
Package forge provides the IssueTracker interface and implementations for GitHub, Gitea, and GitLab. |
|
forge/gitea
Package gitea implements the forge.IssueTracker interface for Gitea using the official Gitea Go SDK.
|
Package gitea implements the forge.IssueTracker interface for Gitea using the official Gitea Go SDK. |
|
forge/github
Package github implements the forge.IssueTracker interface for GitHub using the google/go-github SDK.
|
Package github implements the forge.IssueTracker interface for GitHub using the google/go-github SDK. |
|
hostmetrics
Package hostmetrics collects host-level metrics (disk, RAM, CPU load, swap) via /proc reads and syscall.Statfs on Linux, with zero-value stubs on other platforms.
|
Package hostmetrics collects host-level metrics (disk, RAM, CPU load, swap) via /proc reads and syscall.Statfs on Linux, with zero-value stubs on other platforms. |
|
infra
Package infra implements infrastructure probing for known endpoints (Ollama instances, Samverk services, Gitea) and synchronises the results with Synapset machine memories.
|
Package infra implements infrastructure probing for known endpoints (Ollama instances, Samverk services, Gitea) and synchronises the results with Synapset machine memories. |
|
loganalyst
Package loganalyst queries structured logs and produces AI-powered or fallback natural-language summaries of agent sessions, issues, failures, and arbitrary time ranges.
|
Package loganalyst queries structured logs and produces AI-powered or fallback natural-language summaries of agent sessions, issues, failures, and arbitrary time ranges. |
|
mcp
Package mcp implements the Model Context Protocol (MCP) Streamable HTTP handler.
|
Package mcp implements the Model Context Protocol (MCP) Streamable HTTP handler. |
|
provider
Package provider defines the Provider interface and shared types for AI model inference backends (Ollama, Claude, OpenAI).
|
Package provider defines the Provider interface and shared types for AI model inference backends (Ollama, Claude, OpenAI). |
|
provider/claude
Package claude implements the provider.Provider interface using the Anthropic Claude Messages API over raw net/http (no SDK dependency).
|
Package claude implements the provider.Provider interface using the Anthropic Claude Messages API over raw net/http (no SDK dependency). |
|
provider/claudecli
Package claudecli implements provider.Provider by shelling out to the Claude Code CLI (`claude --print`).
|
Package claudecli implements provider.Provider by shelling out to the Claude Code CLI (`claude --print`). |
|
provider/ollama
Package ollama implements the provider.Provider interface using the Ollama REST API over raw net/http (no SDK dependency).
|
Package ollama implements the provider.Provider interface using the Ollama REST API over raw net/http (no SDK dependency). |
|
provider/openai
Package openai implements the provider.Provider interface using the OpenAI Chat Completions API over raw net/http (no SDK dependency).
|
Package openai implements the provider.Provider interface using the OpenAI Chat Completions API over raw net/http (no SDK dependency). |
|
prwatcher
Package prwatcher monitors open pull requests and auto-merges eligible ones.
|
Package prwatcher monitors open pull requests and auto-merges eligible ones. |
|
scaling
Package scaling provides the policy engine for adaptive worker scaling.
|
Package scaling provides the policy engine for adaptive worker scaling. |
|
status
Package status generates status.md content from live project state.
|
Package status generates status.md content from live project state. |
|
synapset
Package synapset provides a client for the Synapset MCP-based semantic memory service.
|
Package synapset provides a client for the Synapset MCP-based semantic memory service. |
|
version
Package version provides build-injected version information.
|
Package version provides build-injected version information. |
|
pkg
|
|
|
models
Package models defines shared types used across the Samverk system.
|
Package models defines shared types used across the Samverk system. |