terva

mcp
Guvenlik Denetimi
Uyari
Health Uyari
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Gecti
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

An agent harness — a coding agent out of the box, open to anything you can wire a tool to. One hardened Go core, many front ends, pluggable in any language.

README.md

terva.sh

A recorded terva session, played at half speed: the agent asks before each edit and command, one is refused, one is widened to the session, and a question is answered with a note

A session transcript replayed through the real terminal at half speed. The same recording plays at terva.sh; just demo-record remakes it.

What is it?

An agent harness in a single static Go binary: a coding agent out of the box,
open to anything you can wire a tool to. It is built in three layers, and the
logo draws them:

The terva logo pulled apart into its three parts: the orange wildcard is the agent core, the white shell is the harness, and the amber footer block is the base

  • the agent core, the wildcard: one hardened, test-backed agent loop and
    event wire, and one interface to two dozen model providers. It reads no file
    and no environment variable.
  • the harness, the shell: terva's composition and conventions, meaning
    configuration, the permission policy, the model registry, sessions,
    credentials, and the daemon every front end talks to.
  • the base, the footer block: the front ends, and the tools, extensions,
    MCP servers, skills and connectors that reach the world, in any language.

Take the whole binary, or only the piece you need: the core alone in your own
program, the core and harness through the Go SDK or terva rpc, or terva's
harness around another agent. docs/embedding.md compares
the ways in.

Two first-class front ends ship in the box, both clients of that same harness
over its control plane — same sessions, same permissions, same event stream:

  • a terminal UI (terva) — the default: hand-rolled, fast, with slash
    commands, inline images, and message queueing. See docs/tui.md.
  • a web UI (terva web) — a browser control panel, not a viewer: drive
    sessions, approve tool calls, edit settings, watch the transcript stream.
    terva desktop opens the same panel in a native window with its own local
    server. Closing the window stops that server.
    See docs/web.md to serve it and
    docs/web-interface.md for what it shows.

Pick either, or both against the same session — the TUI can also drive a
running terva web daemon as a client (terva attach), so the terminal
becomes disposable and the session survives disconnects. The three shapes and
when to use each are laid out in ways to run terva.
Beyond them: an editor integration over ACP, chat connectors, print/json for
scripting, and an embeddable RPC/SDK.

  • one static binary.
  • built-in providers for Anthropic, OpenAI/Codex/Responses, Kimi, DeepSeek, Google Gemini/Vertex, GitHub Copilot, Bedrock, Azure OpenAI, OpenRouter, Groq, Cerebras, xAI, Together, Hugging Face, Mistral, Moonshot, Z.AI, Xiaomi, MiniMax, Fireworks, Vercel AI Gateway, OpenCode, Cloudflare AI, Ollama, and any OpenAI-compatible local/custom endpoint.
  • the built-in tool set: read, write, edit, bash, read-only grep/glob search, terva_status for agent self-introspection, a task_* board the agent plans with, and session_inspect for reading its own past transcripts. Extension and MCP tool groups start hidden by default and the model activates the ones it needs via activate_tools, so a large integration surface costs no context until it is used ("lazy_tools": false opts out).
  • a permission system: approval modes (plan/ask/auto-edit/workspace/yolo) plus typed permission rules. Interactive sessions default to workspace (built-in tools and reads run; foreign extension/MCP tools that can have side effects ask) and are sandboxed to the working directory by default. See docs/permissions.md.
  • pre/post tool-use hooks (veto, rewrite, or observe tool calls with your own scripts; docs/hooks.md) and an MCP client (attach Model Context Protocol servers as tools; docs/mcp.md).
  • run modes beyond the two UIs: an editor integration over ACP (Agent Client Protocol — drive terva from Zed and other ACP editors), print, json, and a JSON-RPC server for embedding. Every front end is a thin client of one agent loop and one event stream, spoken over the ctrlproto control plane (docs/controllers.md).
  • background subagents: fan work out to parallel swarm agents from within a session.
  • RAATI: convene a panel of models to argue a decision to a recorded verdict, instead of trusting one model's first answer. See docs/raati.md.
  • Talkoot: run a persistent team of agents in one checkout, native terva members beside Claude Code, with roles, budgets, and an inbox where they ask you. Watch it in the Talkoot app that terva web serves. The team can also work while you are away: it reaches you over a chat connector, a member looks at a result again later, and a routine that you approved runs on a schedule and never merges. See docs/talkoot.md and docs/always-on.md.
  • chat connectors: built-in telegram and discord bridges, external
    connectors in any language
    (separate executables speaking a small
    versioned JSON protocol), and connectors bundled inside extensions —
    one wire for all three, with group admission, interactive approvals
    over chat (buttons on Discord), per-chat sessions, speakers, and
    threads. See docs/connectors.md.
  • extensions in any language via subprocess + json-rpc. None installed by default; opt in with terva ext install or terva --ext. See docs/extensions.md.
  • user and extension themes via JSON; see docs/themes.md.
  • localization: translate the UI into your language, or override terva's wording and even its model-facing prompts in place (works in English too) via per-key $TERVA_HOME/locales overlays. See docs/localization.md.
  • reusable instructions via SKILL.md files; see docs/skills.md.
  • optional image generation, two independent opt-in paths: the generate_image tool over a registry of hosted or self-hosted backends (OpenAI/LocalAI, AUTOMATIC1111/Forge, ComfyUI), rendered inline and optionally saved into the workspace; and native image output — the model drawing inline in its own reply via the OpenAI Responses image_generation tool over your Codex subscription, no extra endpoint. See docs/image-generation.md and docs/native-image-output.md.
  • chat & play modes: reframe the harness away from coding — a conversation (--chat) or a roleplay/simulation (--play), fronted by a persona or a SillyTavern character card (--card), with a keyword-triggered lore context engine and a director that can voice a declared cast of actors. See docs/personas.md.
  • no community atm.

Install

One-liner (macOS, Linux)

curl -fsSL https://terva.sh/install.sh | bash

Detects your OS and architecture, downloads the latest release from GitHub, verifies the SHA-256 against the release's checksums.txt, extracts the binary, and drops it in /usr/local/bin, ~/.local/bin, or ~/bin, whichever is writable first. Pass a version or prefix to pin:

curl -fsSL https://terva.sh/install.sh | bash -s -- v0.137.0 ~/bin

One-liner (Windows, PowerShell)

iwr -useb https://terva.sh/install.ps1 | iex

Drops terva.exe into $HOME\bin and adds it to the user PATH if missing. Open a fresh terminal afterwards.

Container

docker run -it --rm -v terva-data:/data ghcr.io/terva-sh/terva --help

Multi-arch images (linux amd64/arm64) publish with each release,
tagged per version and latest. All state lives on the /data volume
(TERVA_HOME); the agent's workspace is /work. Running connector
bots this way — and under systemd — is covered in
docs/deploy.md.

go install

go install terva.sh/terva/cmd/terva@latest

From source

git clone https://github.com/terva-sh/terva   # public mirror; development happens on the maintainer's Forgejo
cd terva
just build        # produces ./bin/terva
just install      # into $GOBIN (else $GOPATH/bin)

Prebuilt binaries

Every release on the releases page ships archives for Linux, macOS, and Windows on amd64 and arm64 (except windows/arm64), plus a checksums.txt file. Each platform comes in two builds: terva (full — every feature compiled in, including the ACP editor mode and the terva desktop window; what the one-liner installs) and terva-min (lean — chat connectors and desktop left out). Both unpack the same terva command. On Linux the full build needs glibc; on musl (Alpine) use terva-min, which the one-liner picks for you, or install gcompat. Download, verify, chmod +x, and drop on your $PATH. CHANGELOG.md lists what changed in each version.

Authenticate

Run terva and type /login — the TUI opens without credentials and walks
you through a browser-based flow, for an API key or a Claude Pro/Max,
ChatGPT Plus/Pro, Kimi Code, or GitHub Copilot subscription. Credentials
resolve in order: --api-key flag → provider env var (ANTHROPIC_API_KEY,
OPENAI_API_KEY, …) → $TERVA_HOME/auth.json. The OAuth flows, token
refresh, and the auth-file format are covered in
docs/providers.md.

Using a subscription login through a third-party tool is a legal gray area
with some providers, and you take full responsibility for how you connect
terva to a provider's service. The terva project itself uses API keys. Read
Provider terms are yours to follow
before you log in with a subscription.

Usage

terva                              # interactive tui
terva "fix the failing test"       # tui, pre-filled prompt
terva -p "list all go files"       # print final text, exit
terva --json "refactor main.go"    # newline-delimited json events, exit
terva --continue                   # resume the most recent session for this cwd
terva --resume                     # pick a session to resume
terva --list-models                # show supported models
terva --chat --persona kaiku       # talk with a companion persona (no tools)
terva --card ./aava.png            # chat as a SillyTavern character card
terva --play --ext ./world         # act in a simulated world extension
terva --help

terva --help lists every flag; the full reference is
docs/cli.md.

Documentation

docs/README.md maps the whole set. Two entry points depending
on what you want:

docs/design/ How terva works, and why — the agent loop, context economics and the prefix cache, the permission chokepoint, the control plane, the extension seams, and the lessons behind each. Written for a programmer who does not necessarily write Go
docs/practices/ Practices for agentic harnesses — what we and the field have learned about building this kind of system, generalized for a harness that is not terva, with the evidence behind each claim graded

The reference guides:

Doc What's in it
docs/cli.md Flags, tools (read/write/edit/bash/grep/glob/terva_status/task_*/session_inspect), run modes, the data directory
docs/secrets.md Secrets at rest (terva secret): the age key a new install generates, backing it up, rotation, and the terva web bearer token
docs/standard-tools.md The tool-surface strategy: core vs standard extension vs MCP preset, and the roadmap for new tools
docs/permissions.md Approval modes (plan/ask/auto-edit/workspace/yolo, with workspace the interactive default), permission rules, the jail-by-default sandbox, and the two rules for work that no person began
docs/hooks.md Pre/post tool-use hooks: veto, rewrite, or observe tool calls with your own scripts
docs/mcp.md Attaching MCP servers as tool providers (stdio, namespaced, permission-gated)
docs/scripting.md The in-engine JavaScript sandbox: code_execution and code_execution_mutating, with the host's tools as functions
docs/tui.md The terminal UI: attaching to a daemon, the status bar, copying text out, sessions, inline images, key bindings
docs/slash-commands.md Every TUI slash command, and what each one does
docs/recording.md Recording a TUI session with asciinema: keeping the capture small, the OSC 9;4 busy signal, and secrets
docs/web.md Running the web control panel (terva web): the listener, reverse proxy, auth, deployment, self-restart, building the client
docs/web-interface.md What the web panel shows: the panes, model picker, usage, slash commands, attachments, shared files
docs/serve.md terva serve: one terva per signed-in person on one host, with containment, enrolment, and the operator panel
docs/fleet.md One browser reading many machines: the hub, members that dial in, and the tunnel between them
docs/models.md Picking models, fallback/rescue, custom catalogs, per-provider notes (Kimi, DeepSeek, Gemini, ollama, OpenAI-compatible)
docs/providers.md Login flows, endpoints, models.json reference, capability tags
docs/connectors.md Chat connectors: the telegram and discord bridges, external connectors in any language, group admission, approvals over chat
docs/connector-protocol.md The connector frame reference: every frame in both directions, protocol 1 and 2, and the feature-string vocabulary
docs/deploy.md Running bots as services: systemd units and the container image, for persistent, resuming, capability-scoped connector agents
docs/scheduled-jobs.md Running terva unattended on a timer: watches, reports, and follow-ups
docs/extensions.md Extensions: writing one, the manifest, discovery, configuration, the SDKs, installing and managing
docs/extension-protocol.md The extension frame reference: every frame in both directions, the protocol version each arrived in, the golden corpus
docs/controllers.md The control-plane protocol (ctrlproto): frames, method groups, events, carriers, and the management-plane horizon
docs/skills.md SKILL.md reusable instructions: anatomy, discovery, authoring
docs/personas.md Personas and immersive chat/play: charters, immersive identities, character cards, the cast + actor_spawn, and the mode flags
docs/raati.md RAATI: the deliberation primitive — several models argue a decision to a recorded verdict
docs/talkoot.md Talkoot: a persistent team of agents in one checkout, with roles, budgets, guards, and an inbox for you
docs/always-on.md Always on: the team reaches you over chat, wakes itself, and runs routines that you approved. The five-minute introduction, with a tour
docs/workflows.md Scripted multi-agent orchestration with terva workflow run: a JavaScript program that spawns and sequences sub-agents
docs/context-construction.md What actually goes into the model's context each turn, and in what order
docs/debugging-prompts.md Inspecting the assembled prompt (--dump-prompt), the lore engine, and card/lore/greeting troubleshooting
docs/prompt-labels.md Reference for the source labels and portability classes that --dump-prompt prints
docs/themes.md User and extension themes
docs/localization.md Translating the UI into another language, and overriding terva's wording or model-facing prompts in place (even in English)
docs/rpc.md Embedding terva: the RPC wire schema and the JSON event stream (Go SDK: packages/agent/sdk, examples under examples/)
docs/resource-limits.md Bounding what a session can spend: turns, tokens, cost, and wall-clock
docs/profiling.md Performance-profiling the harness: the terva_pprof dev build, pprof/GODEBUG capture, and reading a TUI CPU profile
docs/fork.md Lineage: how terva relates to zot, and the compatibility promises
docs/positioning.md The canonical statement of what terva is, which downstream copy derives from
CHANGELOG.md What changed in every released version, newest first

Development

just is the canonical local toolchain (just --list shows every recipe). The
command that matters before you push is the full gate — the same checks CI runs:

just ci        # gofmt + vet, the i18n catalog check, race tests, the
               # terva_acp / terva_web tagged build+test, the terva_pprof and
               # no-connector builds, and the release-overlay sync check
just lint      # gofmt + vet + i18n check (no tests)
just test      # race tests
just build     # ./bin/terva
just install-dev   # non-stripped, pprof-enabled build (see docs/profiling.md)

just ci is the full gate CI enforces — reproduce it before you push. A bare
go test ./... skips the tagged builds, the i18n check, and the overlay check,
so a green partial run is not a green CI.

Source layout (single Go module), grouped by layer:

cmd/terva/                            main()

# the agent core
packages/core/                        agent loop, events, tools, permission seam, cost, compaction
packages/core/{stall,lazytools,...}   components a host attaches with core.WithComponent
packages/provider/                    the wire: Client interface, streaming clients, baked model rows

# the harness
packages/agent/                       cli wiring, arg parsing, config
packages/agent/build/                 Resolve(): the core, assembled with terva's policies and prompt
packages/agent/modelreg/              terva's model registry
packages/session/                     JSONL sessions, the core's transcript store
packages/auth/                        credential store, api-key probe, oauth, login server
packages/agent/swarm/                 background subagent runtime
packages/agent/card/                  SillyTavern Character Card V2 parser (json + png)
packages/agent/lore/                  keyed-context (lore) engine: selection, budget, recursion
packages/agent/sdk/                   public Go SDK: the core and harness in your own process

# the base
packages/tui/                         terminal raw-mode, input parser, editor, renderer, markdown, view
packages/agent/modes/                 interactive tui, print, json, dialogs
packages/agent/tools/                 read, write, edit, bash, terva_status, sandbox
packages/agent/skills/                skill discovery, frontmatter parser, skill tool
packages/agent/extensions/            extension subprocess manager
packages/agent/extproto/              extension wire-format types
packages/agent/ext/                   public Go SDK for writing extensions (package ext)

Downstream consumers can depend on the layers separately:
go get terva.sh/terva/packages/core pulls only the agent core and the wire,
no harness or TUI code. docs/embedding.md says which way in
suits which program, and what each one promises before 1.0.

Lineage

terva began in May 2026 as a hard fork of
patriceckhart/zot and took its own
name once it diverged too far to carry upstream's. It is not a
replacement, successor, or rename — zot lives on as its own project, and the
two have long since gone their separate ways. Existing zot installs keep
working: ZOT_* env vars, legacy data directories, and .zotsession import
all still work, and terva migrate moves you over when you're ready.

docs/fork.md has the full story — what terva grew since the
fork, where the compatibility promises begin and end, and why upstream
tracking was retired.

License

MIT

Yorumlar (0)

Sonuc bulunamadi