# Noetic

> A TypeScript framework for building AI agents, plus a terminal-based coding agent (the Noetic Code Agent CLI). Get started: install `@noetic-tools/core`, set `OPENROUTER_API_KEY`, and run an agent in a few lines.

## Documentation

- [Noetic Documentation](https://noetic.tools/docs): Pick a product to dive into.
- [AGENT.md](https://noetic.tools/docs/code-agent-cli/agent-md): Persistent project and user instructions surfaced into every agent turn.
- [Configuration](https://noetic.tools/docs/code-agent-cli/configuration): noetic.config.ts schema, discovery order, environment variables, and the built-in command and tool registries.
- [Custom Flows](https://noetic.tools/docs/code-agent-cli/custom-flows): Two ways to build long-running, multi-path agent workflows — plan-mode JSON flows and programmatic Step compositions.
- [Hooks](https://noetic.tools/docs/code-agent-cli/hooks): Worktree lifecycle hooks — pre-start, post-start, post-merge, pre-remove — for sub-agent isolation.
- [Code Agent CLI](https://noetic.tools/docs/code-agent-cli): noetic — the interactive terminal coding agent built on the framework.
- [Plugins](https://noetic.tools/docs/code-agent-cli/plugins): Extend the noetic CLI with custom tools, context layers, skills, slash commands, footer UI, sub-agent presets, reminder triggers, and language servers.
- [Rules](https://noetic.tools/docs/code-agent-cli/rules): Granular instruction files in .agent/rules — split AGENT.md into focused, reusable pieces.
- [Skills](https://noetic.tools/docs/code-agent-cli/skills): Markdown + YAML personas — load focused instructions on demand, expose them as slash commands, register them as sub-agent presets.
- [noetic tasks](https://noetic.tools/docs/code-agent-cli/tasks): One concept, one verb namespace, one slash command — the unified task system replaces both the legacy worktree-modal `tasks` and the legacy strategic `mission` flows.
- [ACP Agent Steps](https://noetic.tools/docs/framework/acp-agents): Run any coding agent that speaks the Agent Client Protocol — Claude Code, Codex, Gemini CLI — as a Noetic step.
- [Serving an Agent over ACP](https://noetic.tools/docs/framework/acp-server): Expose a Noetic harness as an Agent Client Protocol agent, so editors like Zed can drive it.
- [Chat SDK Integration](https://noetic.tools/docs/framework/chat-sdk): Run a Noetic agent as the brain of a multi-platform chat bot with @noetic-tools/chat-sdk.
- [Context & Event Log](https://noetic.tools/docs/framework/context): The Context object tracks execution state, metrics, and conversation history.
- [Design Decisions](https://noetic.tools/docs/framework/design-decisions): Key architectural choices behind Noetic and the reasoning that shaped them.
- [Durability](https://noetic.tools/docs/framework/durability): Crash-recovery model for long-running agents — checkpoint/restore, subprocess reattach, durable IPC.
- [Error Model](https://noetic.tools/docs/framework/errors): Noetic uses structured NoeticError objects with error codes and recovery hints.
- [Generative UI](https://noetic.tools/docs/framework/generative-ui): Agents that respond with your UI — via OpenUI — through a streaming output codec, a server-authoritative context layer, tool-authored fragments, and a transport.
- [Getting Started](https://noetic.tools/docs/framework): Install Noetic and build your first agent in under 5 minutes.
- [JSON Workflow Runtime](https://noetic.tools/docs/framework/json-runtime): Generate and execute agent workflows as portable JSON definitions.
- [Migrating from Sub-Harnesses](https://noetic.tools/docs/framework/migrating-from-sub-harnesses): The sub-harness packages are deprecated and replaced by @noetic-tools/acp. What changed, and how to move.
- [Observability](https://noetic.tools/docs/framework/observability): Built-in distributed tracing with OpenTelemetry-compatible spans.
- [Overview](https://noetic.tools/docs/framework/overview): Noetic is a TypeScript agent framework built on eight composable primitives.
- [Prompt Caching](https://noetic.tools/docs/framework/prompt-caching): How Noetic keeps the prompt prefix stable so providers cache it, and how changes are published without rewriting it.
- [AgentHarness](https://noetic.tools/docs/framework/runtime): The AgentHarness executes agent steps, manages context, and coordinates context layers and channels.
- [Context Layer Naming Migration](https://noetic.tools/docs/migration/context-layers): Breaking migration from the former memory/context layer names to Noetic's final context-layer API.
- [Agent Plugins](https://noetic.tools/docs/framework/context-layers/agent-plugins): A conformant Agent Plugins v1 client — discovers plugin packages from agent-plugins.org and exposes their Agent Skills and MCP servers to the model using progressive disclosure.
- [Custom Context Layers](https://noetic.tools/docs/framework/context-layers/custom-layers): How to build your own context layer by implementing ContextLayerHooks, choosing a slot and scope, and configuring budgets and timeouts.
- [Episodic Context](https://noetic.tools/docs/framework/context-layers/episodic-context): A context layer that stores and retrieves summaries of past conversation episodes for long-running agents.
- [Filesystem](https://noetic.tools/docs/framework/context-layers/filesystem): A context layer that tracks
- [History](https://noetic.tools/docs/framework/context-layers/history): A read-side context layer that caps the trailing items projected to the LLM without mutating storage.
- [Context Layer System](https://noetic.tools/docs/framework/context-layers): How Noetic's context layers inject long-term and short-term context into every LLM call through a slot-based, scoped architecture.
- [Instructions](https://noetic.tools/docs/framework/context-layers/instructions): A read-only context layer that loads instructional content once at init and injects it into every recall, wrapped in an XML tag.
- [Observations](https://noetic.tools/docs/framework/context-layers/observations): A context layer that automatically extracts and distills facts from conversation history using a configurable observer function.
- [Plan](https://noetic.tools/docs/framework/context-layers/plan): PRD authoring and plan execution lifecycle with tool restrictions during planning.
- [Scratchpad](https://noetic.tools/docs/framework/context-layers/scratchpad): A scratchpad context layer that persists structured or free-form notes across turns within a single execution.
- [Semantic Recall](https://noetic.tools/docs/framework/context-layers/semantic-recall): Vector-indexed long-term recall for retrieving relevant past knowledge using embedding similarity search.
- [Steering](https://noetic.tools/docs/framework/context-layers/steering): A context layer that enforces behavioral rules before tool calls and after model responses, with programmatic and LLM-evaluated rules.
- [Task State](https://noetic.tools/docs/framework/context-layers/task-state): Persistent agent checkpoints that survive crashes and enable long-running task recovery.
- [Temporal](https://noetic.tools/docs/framework/context-layers/temporal): An LLM-backed context layer that distills the conversation into a ledger of timestamped facts and answers relative-time queries on demand.
- [Tool Calls](https://noetic.tools/docs/framework/context-layers/tool-calls): How tools expose imperative state and function-call interfaces to context layers and LLMs.
- [Branching Agent](https://noetic.tools/docs/framework/examples/branching-agent): A support ticket router using conditional, runCode, callModel, and loop to classify and handle tickets by keyword.
- [Deep Agent (DeepAgentsJS Recreation)](https://noetic.tools/docs/framework/examples/deep-agent): A full-featured coding agent with filesystem access, task planning, sub-agent delegation, skills, and context — built entirely from Noetic primitives.
- [Examples](https://noetic.tools/docs/framework/examples): Composite operation examples showing how Noetic's eight primitives compose into real agent patterns.
- [Parallel Research](https://noetic.tools/docs/framework/examples/parallel-research): A research agent using inParallel (all mode) with spawn-wrapped LLM calls to investigate a topic from multiple perspectives in parallel.
- [Pipeline Agent](https://noetic.tools/docs/framework/examples/pipeline-agent): A 3-stage text processing pipeline using conditional, runCode, callModel, loop, and prepareNext to chain sequential stages.
- [Adapter Types](https://noetic.tools/docs/framework/api/adapter-types): OpenRouter adapter and EmbedFn type for semantic routing and convergence.
- [Channel Types](https://noetic.tools/docs/framework/api/channel-types): Type definitions for channels, external channels, and channel handles in Noetic.
- [Context Layer Types](https://noetic.tools/docs/framework/api/context-layer-types): Type definitions for context layers, hooks, storage adapters, and projection policies in Noetic.
- [Context Types](https://noetic.tools/docs/framework/api/context-types): Type definitions for Context, ItemLog, Item variants, and content parts in Noetic.
- [API Reference](https://noetic.tools/docs/framework/api): Complete type reference for all @noetic-tools/core exports, organized by category.
- [Items & Events](https://noetic.tools/docs/framework/api/items-and-events): Complete reference for all item shapes and streaming events, aligned with the OpenResponses specification.
- [AgentHarness Types](https://noetic.tools/docs/framework/api/runtime-types): Type definitions for the AgentHarnessContract interface, AgentConfig, and related types in Noetic.
- [Step Types](https://noetic.tools/docs/framework/api/step-types): Type definitions for all step variants in Noetic's discriminated union.
- [Until Types](https://noetic.tools/docs/framework/api/until-types): Type definitions for termination predicates, verdicts, snapshots, and combinators in Noetic.
- [Channels](https://noetic.tools/docs/framework/operators/channels): Typed communication channels for inter-step and inter-process messaging.
- [conditional](https://noetic.tools/docs/framework/operators/conditional): Conditional routing -- pick one step to execute or skip entirely.
- [Semantic Conditions](https://noetic.tools/docs/framework/operators/conditions): AI-powered routing with embeddings, LLM classifiers, and condition combinators.
- [inParallel](https://noetic.tools/docs/framework/operators/in-parallel): Run multiple steps in parallel with race, all, or settle semantics.
- [Loop & Until](https://noetic.tools/docs/framework/operators/loop-and-until): Repeat a step until a termination predicate says stop.
- [spawn](https://noetic.tools/docs/framework/operators/spawn): Run a child step in an isolated context with optional spawn-local context layers.
- [withContext](https://noetic.tools/docs/framework/operators/with-context): Attach context layers to descendant steps without creating an isolated context.
- [callModel](https://noetic.tools/docs/framework/steps/call-model): Call a language model with tools, structured output, and system prompts.
- [Steps](https://noetic.tools/docs/framework/steps): The three step primitives -- runCode, callModel, and invokeTool -- are the atomic units of work in Noetic.
- [invokeTool](https://noetic.tools/docs/framework/steps/invoke-tool): Invoke a single tool directly as a typed step.
- [runCode](https://noetic.tools/docs/framework/steps/run-code): Execute arbitrary async code as a typed step.