Subconscious

Inference systems designed for agents.

---

What is Subconscious?

Subconscious is an AI lab that makes open language models dramatically more capable with our inference runtime TIMRUN and complementary post-trained TIM family of models.

Learn more at subconscious.dev.

Quick Start

Subconscious is OpenAI-compatible. Point the official OpenAI SDK at our base URL — no proprietary SDK to install.

Install the SDK

# Node.js / TypeScript
npm install openai

# Python
pip install openai

Get your API key at subconscious.dev/platform. The base URL is https://api.subconscious.dev/v1 and the default model is subconscious/glm-5.2.

Run your first agent

TypeScript

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.subconscious.dev/v1',
  apiKey: process.env.SUBCONSCIOUS_API_KEY,
});

const completion = await client.chat.completions.create({
  model: 'subconscious/glm-5.2',
  messages: [{ role: 'user', content: 'Explain what an API is in 3 sentences.' }],
});

console.log(completion.choices[0].message.content);

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.subconscious.dev/v1",
    api_key="your-api-key",
)

completion = client.chat.completions.create(
    model="subconscious/glm-5.2",
    messages=[{"role": "user", "content": "Explain what an API is in 3 sentences."}],
)

print(completion.choices[0].message.content)

Thinking is on by default — the model prepends a reasoning preamble to its reply. For clean, fast answers on chat / structured / classification tasks, pass extra_body={"chat_template_kwargs": {"enable_thinking": False}} (Python) or chat_template_kwargs: { enable_thinking: false } on the request body (TypeScript). Leave it on for hard multi-step reasoning.

Model

Available models include:

• subconscious/glm-5.2 (default)
• subconscious/tim-qwen3.6-27b
• subconscious/deepseek-v4-flash-marathon

They are served behind the OpenAI-compatible endpoint. /v1/models reports the public fleet catalog. /v1/models/available reports the models the authenticated API key may call. The subc CLI fetches the provisioned list when a profile key is present, falls back to the public catalog, and uses packaged defaults only when discovery is offline.

Tools

Subconscious supports standard OpenAI function tools. You pass a tools array; when the model wants one, the reply comes back with tool_calls. You run the function and send the result back as a role: "tool" message — Subconscious does not execute tools for you, so the loop is client-side.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {"city": {"type": "string"}},
            "required": ["city"],
        },
    },
}]

resp = client.chat.completions.create(
    model="subconscious/glm-5.2",
    messages=[{"role": "user", "content": "What's the weather in Boston?"}],
    tools=tools,
)
# resp.choices[0].message.tool_calls -> run them, append role:"tool" results, loop.

Want MCP tools? Connect to the MCP server client-side, convert its tools to OpenAI function tools, and dispatch tool_calls back to it — see the cli_agent and Boston notebook examples.

What's in this repo

Developer-facing tooling for building on Subconscious:

• cli/ — subconscious-cli: use subc to authenticate and run the packaged coding-agent integrations
• examples/ — runnable example agents and templates
• create-subconscious-app/ — scaffold a new project from any example
• scripts/ — repo tooling (example manifest generation)

CLI

Log in to Subconscious from your terminal, then launch or configure coding agents.

npm install -g subconscious-cli
subc login                           # sign in, saves your API key
subc sc                              # launch Subconscious Code
subc claude                          # launch Claude Code on Subconscious
subc dsh                             # launch DeepSeek Harness on Subconscious
subc cursor install                  # merge Cursor hooks

subc <agent> resolves your saved API key and runs the packaged integration. Terminal agents launch directly; Cursor, Copilot, and Pi persist a surgical integration with subc <agent> install. Login also creates a secure default profile.

Command	Behavior
subc sc	Launch the native Subconscious Code agent (or subc sc install)
subc claude	Launch Claude Code
subc codex	Launch Codex CLI (merges compaction hooks)
subc opencode	Launch OpenCode
subc dsh	Launch DeepSeek Harness with the live Subconscious model catalog
subc cursor install	Configure Cursor hooks
subc copilot install	Configure VS Code Copilot endpoint + hooks
subc pi install then subc pi	Configure, then launch Pi

Use subc <agent> help or subc config help for command-specific usage. subc config lists profiles and their .env paths; subc -p NAME config prints the file, and subc config edit vim (or nano) opens it. Extra keys in that file override Subconscious-injected launch defaults. Agent-specific credentials override the shared profile key and also work when no shared key is configured.

subc cursor uninstall
subc pi uninstall
subc -p staging claude

Other commands: update-key <key> replaces your saved key, update-url <url> automatically changes the active profile's gateway, logout removes the key, and whoami shows your current auth status. Keys are saved to ~/.subconscious/config.json (owner-read-only); SUBCONSCIOUS_API_KEY takes precedence. See cli/README.md for details.

Examples

Runnable example agents and templates, each in its own folder under examples/.

Example	Description	Stack
Vercel Agent Runner	Full-stack Next.js app with streaming UI, tool management, and one-click Vercel deploy	Next.js, TypeScript
CLI Agent	Clone-and-go terminal agent: client-side ReAct loop over MCP tools	TypeScript, Ink, MCP
E2B CLI Agent	Autonomous CLI agent with E2B cloud sandboxes for code execution and file I/O	TypeScript, E2B
Convex Real-time App	AI todo assistant with real-time updates backed by Convex	React, Convex, TypeScript
Composio Agent	100+ OAuth apps as agent tools via Composio, executed in a client-side loop	Python
Local-Hosted Tools	Client-side tool loop with local Python functions; image-editing demo	Python
Structured Output (Python)	Type-safe structured responses via Pydantic + response_format	Python, Pydantic
Structured Output (TypeScript)	Type-safe structured responses via Zod + response_format	TypeScript, Zod
Getting Started Notebook	Colab walkthrough — no setup required	Python, Jupyter
City of Boston Getting Started	Colab notebook tailored to the City of Boston POC	Python, Jupyter

create-subconscious-app

The fastest way to start from an example is to scaffold it with the CLI:

npx create-subconscious-app

This launches an interactive prompt that fetches the latest examples from this repo and sets one up for you. You can also skip the prompts:

npx create-subconscious-app my-agent -e e2b_cli    # scaffold a specific example
npx create-subconscious-app --list                  # list all available examples

Adding your own example

1. Create a folder under examples/ with your project code.
2. Add metadata (package.json for JS/TS or pyproject.toml for Python) with name, description, and an optional setup array of post-scaffold instructions.
3. Open a PR. When it merges, a GitHub Action regenerates examples/manifest.json and your example becomes available via npx create-subconscious-app immediately.

Scripts

scripts/generate-manifest.js reads each example's metadata and regenerates examples/manifest.json — the manifest that create-subconscious-app and the templates page consume.

node scripts/generate-manifest.js

A GitHub Action runs this automatically on push to main, and validates the manifest on PRs.

Documentation & resources

• Subconscious
• Documentation
• Platform & Playground
• Hugging Face

Support

• Email: support@subconscious.dev
• Issues: GitHub Issues
• Docs: docs.subconscious.dev