Guga Agent

A small-core, plugin-first, recoverable, auditable, embeddable Agent Runtime.

English | Chinese | Japanese

---

What Is Guga Agent

Guga Agent is a TypeScript runtime monorepo for builders of agent products. It does not start as a large chat application that later gets split into an SDK. Instead, it starts with the load-bearing parts of real agent systems: model calls, tool execution, permissions, context, events, plugins, session storage, artifacts, and replay all live behind clear runtime boundaries.

In one sentence: Guga Agent helps turn a working agent demo into an agent system that can be shipped, recovered, audited, and embedded in real products.

What Problems It Solves

Many agent prototypes look like "a model plus tools", but the same problems appear as soon as they touch real workflows:

• Long tasks hit context overflow, and it is unclear whether the agent can continue safely after compaction.
• Tools can read files, write files, and execute commands, but permissions, audit trails, and result feedback are scattered.
• Provider SDK types leak into the main loop, making model switching, retry, and fallback global concerns.
• UI, CLI, IDE, and API clients all want to observe the same run, but each ends up parsing strings and temporary state.
• Sessions survive only in memory, making crashes, cancellation, restart, branching, and replay fragile.
• More plugins and tools keep getting added, but order, namespaces, permissions, and stale context are not governed consistently.

Guga's answer is to move these concerns into the runtime: the model proposes intent, the runtime owns execution boundaries; context is a projection, not the only source of truth; events are the ledger that UI and audit views derive from.

Design Philosophy

Small Core, Large Periphery

@guga-agent/core owns only the agent lifecycle, state machine, events, hooks, capability registration, permission protocol, tool execution pipeline, and core contracts. Real providers, filesystem access, shell execution, git helpers, session stores, artifact stores, and context policies connect as plugins.

Plugins Are First-Class

First-party capabilities and host-defined capabilities use the same plugin context: register providers, tools, hooks, stores, or context policies. Plugins cannot mutate core state directly; they participate through explicit capability registration and typed hook results.

Events Are The Source Of Facts

Model requests, tool calls, permission decisions, hook decisions, usage, artifacts, errors, compaction boundaries, and replay hints should all become recordable facts. The final answer is only the result; the event ledger is the foundation for recovery and audit.

Permissions Are Enforced By Runtime

The model can explain why it wants to perform an action, but it cannot authorize itself. Every tool intent goes through ExecutionPipeline: schema checks, hooks, permission resolution, scheduling, timeout, result policy, and event recording.

Context Is A Projection

Model input is not an ever-growing concatenation of history. It is projected from conversation state, context sources, artifact references, compaction boundaries, and policy. Summaries extend endurance; they are not the only source of truth.

Commercial Capability Grows Gradually

Guga does not try to build a full marketplace, long-term memory, multi-agent swarm, or enterprise console on day one. It first stabilizes loop, tool, provider, context, session, and replay boundaries, then lets product capabilities grow through the plugin ecosystem.

Current Capabilities

Capability	Package	Description
Core Runtime	@guga-agent/core	Provider-neutral messages, AgentLoop, ConversationState, canonical registration for tools, skills, agents, and workflows, EventBus, ProviderRouter, hooks, permissions, and the tool execution pipeline.
Application Composition	@guga-agent/application	Compiles one manifest from provider, model, tool, skill, agent, workflow, and plugin contributions; owns safe discovery, application lifecycle, and generation-pinned isolated runtime views.
Durable Orchestration	@guga-agent/orchestration	Compiles and runs durable workflows, resolves registered agent policies, creates fresh/fork child contexts, and adapts existing delegation through coordination ports.
Host Product Surface	@guga-agent/host-runtime and host-*	Exposes safe agent/workflow definitions, authorized run controls, lifecycle events, metrics, and transport parity across HTTP/SDK/stdio/ACP.
Built-in Provider And Tools	@guga-agent/core/builtins	Provides the AI SDK provider bridge plus filesystem, shell, patch, and Git tools behind the same core-controlled permission and execution pipeline.
Managed Process Runtime	@guga-agent/core/builtins	Default Code Agent execution plugin for sandboxed foreground/background commands, real PTY control, cancellation, bounded progress, and durable Guga Home logs.
JSONL Session Store	@guga-agent/plugin-session-jsonl	Local-first append-only event/session store with revision checks, idempotency, hash-chain continuity, and corruption diagnostics.
Artifact Store	@guga-agent/plugin-artifact-filesystem	Stores large tool outputs and replay artifacts in the filesystem while events keep bounded previews and verifiable references.
Replay Audit	@guga-agent/plugin-replay-audit	Derives conversation, model-input, and audit timelines from durable facts without rerunning providers, tools, or mutating hooks.
Default Context Policy	@guga-agent/plugin-context-default	Registers the default context policy and hooks for resources, assemble, budget, truncate, compact, and reinject phases.

Usage

This repository is currently closer to a runtime/workbench foundation than a published terminal application. Development and verification start with the monorepo commands:

pnpm install
pnpm build
pnpm test
pnpm typecheck

A minimal host usually creates a runtime, mounts a provider and plugins, then runs a turn:

import { createAgentRuntime } from "@guga-agent/core";
import { createAiSdkProviderPlugin, createFilesystemPlugin } from "@guga-agent/core/builtins";
import { createJsonlSessionPlugin } from "@guga-agent/plugin-session-jsonl";

const runtime = createAgentRuntime({
  plugins: [
    createAiSdkProviderPlugin({
      id: "local-provider",
      mode: "openai-compatible",
      modelId: "local-model",
      baseURL: "http://localhost:11434/v1",
      apiKey: "test",
      metadata: {
        purposes: ["primary"],
        capabilities: { toolCalling: true, usage: "optional" }
      }
    }),
    createFilesystemPlugin({ workspaceRoot: process.cwd() }),
    createJsonlSessionPlugin({ rootDir: ".guga/sessions" })
  ]
});

Relationship To OpenCode And Pi Agent

Guga learns from mature open-source agent projects, but it has a different product center of gravity:

• OpenCode is closer to a complete open-source coding agent product, with emphasis on TUI, client/server architecture, multi-provider support, and direct user experience.
• Pi Agent is closer to a self-extensible agent harness, with emphasis on monorepo structure, runtime, extensions, sessions, and the data flywheel.
• Guga aims to provide a runtime foundation for agent product builders. It prioritizes embeddable runtime boundaries so CLI, Web, IDE, worker, and enterprise console surfaces can share the same source of runtime facts.

Roadmap Direction

• Keep the unified application registry and durable orchestration contracts small while migrating remaining first-party composition callers.
• Attach definition/run lineage to richer eval, telemetry, audit, and workbench navigation without exposing trusted instructions.
• Extend workflow triggers or distributed execution only after the current local durability and authorization contracts survive real product pressure.
• Continue model operations, cost tracking, credential pools, remote sandboxes, and enterprise policy as optional outer-layer capabilities.

Current Status

Guga Agent now has a runnable CLI/workbench foundation plus a unified application manifest, first-class registered agents/workflows, durable workflow recovery, fresh/fork subagent contexts, and Host transport parity. It remains a runtime platform rather than a polished general-purpose desktop product, and the compatibility factories stay available while composition migrates incrementally.

If you want to build on it, treat it as an agent runtime foundation rather than a simple chat UI wrapper.

License

This project is licensed under the Apache License 2.0. See LICENSE.