b2ae12ad02
## Summary
- prewarm session `connected_integrations` from the shared Composio cache during `from_config_*` agent construction
- synthesize delegation tools against the prewarmed integration view so fresh sessions start with the correct `delegate_<toolkit>` surface
- skip the turn-1 integration fetch and delegation-surface rebuild when the builder already had an authoritative cache snapshot
- carry the runtime `Config` snapshot on the session agent so mid-session integration-cache probes stop reloading config on the hot path
- add a regression test for the initialized/hash bookkeeping when integrations are injected onto an agent
## Problem
- Fresh agent sessions were doing avoidable cold-start work inside `Agent::turn()` before the first provider call.
- On a new session, the turn path loaded transcript state, fetched connected integrations, rebuilt delegation tools, fetched learned context, and only then froze the system prompt.
- The integration fetch itself reloaded `Config` inside the hot path, and the session builder always synthesized delegation tools against an empty integration set, guaranteeing a repair pass on turn 1.
- That inflated first-token latency for orchestrator-style sessions even when the Composio cache already had a valid integration snapshot.
## Solution
- Reuse `composio::cached_active_integrations(config)` during session construction to prewarm `connected_integrations` when the shared cache is already warm.
- Build delegation tools against that cached integration slice instead of hardcoding `&[]`, then persist the synthesized-tool name set onto the built `Agent`.
- Track whether a session's integration view is authoritative with `connected_integrations_initialized`; turn 1 now only fetches integrations and refreshes delegation tools when the builder could not prewarm the cache.
- Store the full runtime `Config` snapshot on the session agent so mid-session cache reads and fallback integration fetches do not call `Config::load_or_init()` on the hot path.
- Keep the existing fallback behavior for cold-cache sessions and shared-`Arc` reconciliation failures so correctness stays unchanged when prewarming is unavailable.
## Submission Checklist
> If a section does not apply to this change, mark the item as `N/A` with a one-line reason. Do not delete items.
- [x] Tests added or updated (happy path + at least one failure / edge case) per [Testing Strategy](../gitbooks/developing/testing-strategy.md#failure-path-requirement)
- [x] N/A: diff coverage is enforced by CI; local coverage commands were blocked in this environment (`pnpm` unavailable on PATH, focused Rust tests blocked by missing `cmake`).
- [x] Coverage matrix updated — `N/A: behaviour-only change`
- [x] All affected feature IDs from the matrix are listed in the PR description under `## Related`
- [x] No new external network dependencies introduced (mock backend used per [Testing Strategy](../gitbooks/developing/testing-strategy.md#mock-policy))
- [x] Manual smoke checklist updated if this touches release-cut surfaces ([`docs/RELEASE-MANUAL-SMOKE.md`](../docs/RELEASE-MANUAL-SMOKE.md))
- [x] Linked issue closed via `Closes #NNN` in the `## Related` section
## Impact
- Runtime/platform impact: desktop/in-process core agent sessions.
- Performance: reduces first-turn latency when the Composio cache is already warm by avoiding a redundant integration fetch, avoiding a redundant delegation-tool rebuild, and avoiding `Config::load_or_init()` on subsequent cache probes.
- Compatibility: cold-cache sessions preserve the old fallback behavior and still fetch integrations on turn 1 when no prewarmed snapshot exists.
- Security: no change in privilege or network surface; this only changes when cached integration metadata is reused.
## Related
- Closes:
- Follow-up PR(s)/TODOs:
---
## AI Authored PR Metadata (required for Codex/Linear PRs)
> Keep this section for AI-authored PRs. For human-only PRs, mark each field `N/A`.
### Linear Issue
- Key: N/A
- URL: N/A
### Commit & Branch
- Branch: feat/agent-spawn-depth-gate
- Commit SHA: 44ca700909
### Validation Run
- [x] N/A: local environment does not have `pnpm` on PATH, so this command could not be run here.
- [x] N/A: local environment does not have `pnpm` on PATH, so this command could not be run here.
- [x] N/A: focused Rust tests were attempted, but the build is blocked locally because `whisper-rs-sys` requires `cmake`, which is not installed in this environment.
- [x] Rust fmt/check (if changed): `cargo fmt --manifest-path Cargo.toml` passed; `git diff --check origin/main...HEAD` clean.
- [x] N/A: Tauri shell files were not changed in this PR; a local `cargo check --manifest-path app/src-tauri/Cargo.toml` attempt was also blocked because the vendored `tauri-cef` dependency tree is missing in this environment.
### Validation Blocked
- `command:` `GGML_NATIVE=OFF cargo test --manifest-path Cargo.toml set_connected_integrations_marks_session_initialized_and_updates_hash -- --nocapture` and `GGML_NATIVE=OFF cargo test --manifest-path Cargo.toml turn_without_tools_returns_text -- --nocapture`
- `error:` `whisper-rs-sys` build script failed because `cmake` is not installed in the local environment
- `impact:` focused Rust tests did not complete locally; correctness is based on source review plus the added regression coverage
### Behavior Changes
- Intended behavior change: sessions built from a warm Composio cache now start with prewarmed integrations and delegation tools instead of repairing that state inside the first turn
- User-visible effect: lower first-token latency for fresh orchestrator-style sessions when integration metadata is already cached
### Parity Contract
- Legacy behavior preserved: when the Composio cache is cold or unavailable, turn 1 still fetches integrations and rebuilds the delegation surface before freezing the prompt
- Guard/fallback/dispatch parity checks: shared-`Arc` reconciliation fallback, mid-session cache-driven refresh, and config-load fallback behavior remain intact
### Duplicate / Superseded PR Handling
- Duplicate PR(s): none
- Canonical PR: this PR
- Resolution (closed/superseded/updated): N/A
<!-- This is an auto-generated comment: release notes by coderabbit.ai -->
## Summary by CodeRabbit
* **New Features**
* Enforced sub-agent spawn-depth limit (max 3) with surfaced error on overflow.
* Sessions now preload and track connected integrations and their runtime config.
* Connected integrations now include a gated-tools catalogue describing hidden toolkit actions.
* **Tests**
* Added tests for spawn-depth enforcement and reset behavior.
* Added tests validating integration-initialization state and hash updates.
* **Documentation**
* Marked spawn-depth runtime limiter as implemented in architecture docs.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/tinyhumansai/openhuman/pull/2454?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: SRIKANTH A <yatheendrudusrikanth@gmail.com>
Co-authored-by: M3gA-Mind <megamind@mahadao.com>
OpenHuman
OpenHuman is your Personal AI super intelligence. Private, Simple and extremely powerful.
Discord • Reddit • X/Twitter • Docs • Follow @senamakel (Creator)
🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇩🇪 Deutsch
Early Beta: Under active development. Expect rough edges.
To install or get started, either download from the website over at tinyhumans.ai/openhuman or run
# Download DMG, EXEs over at https://tinyhumans.ai/openhuman or run in from your terminal
# For macOS or Linux x64
curl -fsSL https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.sh | bash
# For Windows
irm https://raw.githubusercontent.com/tinyhumansai/openhuman/main/scripts/install.ps1 | iex
What is OpenHuman?
OpenHuman is an open-source agentic assistant designed to integrate with you in your daily life. Each bullet links to the deeper writeup in the docs.
-
Simple, UI-first & Human A clean desktop experience and short onboarding paths take you from install to a working agent in a few clicks — no config-first setup, no terminal required. The agent has a face: a desktop mascot that speaks, reacts to its surroundings, joins your Google Meets as a real participant, remembers you across weeks, and keeps thinking in the background even when you've stopped typing.
-
118+ third-party integrations with auto-fetch: plug into Gmail, Notion, GitHub, Slack, Stripe, Calendar, Drive, Linear, Jira and the rest of your stack with one-click OAuth. Every connection is exposed to the agent as a typed tool, and every twenty minutes the core walks each active connection and pulls fresh data into the memory tree. No prompts, no polling loops you have to write, so the agent already has tomorrow's context this morning.
Managed integrations are backend-proxied through OpenHuman's Composio connector layer. If you want to run Composio directly instead of using the managed backend path, configure direct mode with your own Composio API key; real-time trigger webhooks then need to be hosted and wired by you.
-
Memory Tree + Obsidian Wiki: a local-first knowledge base built from your data and your activity. Everything you connect is canonicalized into ≤3k-token Markdown chunks, scored, and folded into hierarchical summary trees stored in SQLite on your machine. The same chunks land as
.mdfiles in an Obsidian-compatible vault you can open, browse and edit, inspired by Karpathy's obsidian-wiki workflow. -
Batteries included: web search, a web-fetch scraper, a full coder toolset (filesystem, git, lint, test, grep), and native voice (STT in, ElevenLabs TTS out, mascot lip-sync, live Google Meet agent) are wired in by default. Model routing sends each task to the right LLM (reasoning, fast, or vision) under one subscription. No "install a plugin to read files" friction. Optional local AI via Ollama for on-device workloads.
-
Smart token compression (TokenJuice): every tool call, scrape result, email body, and search payload is run through a token compression layer before it touches any LLM Model. HTML is converted to Markdown, long URLs are shortened, and verbose tool output is deduped and summarized via a configurable rule overlay etc... CJK, emoji, and other multi-byte text are preserved grapheme-by-grapheme — never stripped. You get the same information but at a fraction of the tokens. Reducing cost & latency by up to 80%.
-
Messaging channels and privacy & security: inbound/outbound across the channels you already use, with workflow data that stays on device, encrypted locally, treated as yours.
Contributing from source
New contributor? Start with CONTRIBUTING.md for the fork/PR workflow and local validation commands, or use the copy-paste AI-agent prompt in CONTRIBUTING-BEGINNERS.md. The short path is:
- Install Git, Node.js 24+, pnpm 10.10.0, Rust 1.93.0 (
rustfmt+clippy), CMake, Ninja, ripgrep, and the platform desktop build prerequisites. - Fork and clone the repo, then run
git submodule update --init --recursivebeforepnpm installso the vendored Tauri/CEF sources are present. - Use
pnpm devfor web-only UI work,pnpm --filter openhuman-app dev:appfor the desktop shell, and focused checks such aspnpm typecheck,pnpm format:check, andcargo check -p openhuman --libbefore opening a PR.
Deeper docs: Architecture · Getting Set Up · Cloud Deploy.
Context in minutes, not weeks
OpenHuman is the first agent harness that gets to know you in minutes. Inspired by Karpathy's LLM Knowledgebase. Most agents start cold. Hermes learns by watching you work; OpenClaw waits for plugins to ferry context in. Either way, you spend days or weeks before the agent knows enough about your stack to be genuinely useful.
OpenHuman summarizes and compresses all your documents, emails & chats; and creates a memory graph that lets your agent remember everything about you.
OpenHuman skips the wait. Connect your accounts, let auto-fetch pull data locally on a 20-minute loop, and then have Memory Trees compress everything into Markdown files stored intelligently in a Karpathy-style Obsidian wiki.
In just one sync pass, the agent has full (compressed) context of your inbox, your calendar, your repos, your docs, your messages. No training period. No "give it a few weeks.". It becomes you, controlled by you.
Already self-host agentmemory across other coding agents? OpenHuman ships an optional Memory backend that proxies to it — set memory.backend = "agentmemory" in config.toml and the same durable store powers OpenHuman alongside Claude Code, Cursor, Codex, and OpenCode. See the agentmemory backend page for setup.
OpenHuman vs Other Agent Harnesses
High-level comparison (products evolve, so verify against each vendor). OpenHuman is built to minimize vendor sprawl, keep workflow knowledge on-device, and give the agent a persistent memory of your data, not only chat.
| Claude Cowork | OpenClaw | Hermes Agent | OpenHuman | |
|---|---|---|---|---|
| Open-source | 🚫 Proprietary | ✅ MIT | ✅ MIT | ✅ GNU |
| Simple to start | ✅ Desktop + CLI | ⚠️ Terminal-first | ⚠️ Terminal-first | ✅ Clean UI, minutes |
| Cost | ⚠️ Sub + add-ons | ⚠️ BYO models | ⚠️ BYO models | ✅ One sub + TokenJuice |
| Memory | ✅ Chat-scoped | ⚠️ Plugin-reliant | ✅ Self-learning | 🚀 Memory Tree + Obsidian vault, optional agentmemory backend |
| Integrations | ⚠️ Few connectors | ⚠️ BYO | ⚠️ BYO | 🚀 118+ via OAuth |
| Auto-fetch | 🚫 None | 🚫 None | 🚫 None | ✅ 20-min sync into memory |
| API sprawl | 🚫 Extra keys | 🚫 BYOK | 🚫 Multi-vendor | ✅ One account |
| Model routing | 🚫 Single model | ⚠️ Manual | ⚠️ Manual | ✅ Built-in |
| Native tools | ✅ Code-only | ✅ Code-only | ✅ Code-only | ✅ Code + search + scraper + voice |
Star us on GitHub
Building toward AGI and artificial consciousness? Star the repo and help others find the path.
Contributors Hall of Fame
Show some love and end up in the hall of fame. Contributors get free merch and special access to our Discord.