hara

A coding agent CLI that runs like an engineering org.

Think "Claude Code, but it operates as a configurable, governed organization of role-agents" — with routing boundaries, a dispatcher, a single source-of-truth data layer, human-in-the-loop approvals, and cron autonomy.

· TypeScript · local-first · Apache-2.0

Highlights

• An org, not just an agent — hara org "<task>" routes work to the role that owns it; hara plan "<task>" decomposes a task into a verified DAG of atoms (frame → atomize → sequence → execute → verify gate), and hara plan --parallel runs independent atoms concurrently.
• Drive it from chat — hara gateway runs your local hara from Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal (10 platforms), with two-way images where the platform has a byte-upload API, resumable per-chat sessions, project/agent roaming, bounded per-thread queues, and approval-gated group automations. Connects out — no public webhook. See docs/gateway.md.
• Relay native coding sessions through Hara — Hara Live starts an isolated Codex or Claude Code terminal in a selected local workspace and lets Desktop or the owner-only /coding gateway commands message, read, and interrupt it. Provider history stays in its original runtime, Hara exposes only opaque local ids, and ordinary chat is never injected into a terminal.
• Real terminal UX — an ink TUI: bottom-pinned input box, plan mode (read-only investigation → the model submits its plan via exit_plan → approve → execute), narrowly scoped project approvals, private model reasoning, paste images (Ctrl+V) for vision models, light/dark theme.
• Reviewed business learning + durable memory — while tasks run, learning_capture records only bounded, redacted evidence as personal/project candidates or local organization proposals. Nothing changes future behavior until the user approves it, or an administrator approves and versions it in Hara Control; learning never expands permissions. Inspect with hara learning list and approve/reject/revoke explicitly. The separate memory_* layer retains curated facts/preferences, while /evolve status|now distills reviewable candidates and verified skills without rewriting product code, permissions, config, or system prompts.
• Multi-provider, all streamed — Anthropic (Claude), Volcengine Ark Agent Plan, or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI), with live Markdown answers while provider reasoning stays private.
• Delegate to other agents — the external_agent tool hands a self-contained task to Claude Code or Codex running headless, and returns the result — so you pick the best engine per task. It is a trusted extension outside Hara's protected-file boundary: every interactive call requires confirmation, and non-interactive use is disabled by default.
• Honest under a slow network — a live "waiting for the model… Ns" status, a stall watchdog that auto-fails-over instead of hanging, terminal-native bracketed paste, big pastes folding to a token, and a startup update notice — the terminal never feels dead.
• Solid coding core — edit_file / apply_patch (atomic multi-file) with colored diffs · grep/glob/ls/codebase_search (lexical + optional semantic search over the repo) /web_fetch · fuzzy @file · /undo · /compact · Esc-to-interrupt · parallel sub-agents · MCP client · macOS sandbox.

Track it: https://github.com/hara-cli/hara · https://hara.run

Install

The npm package requires Node.js 22.23.1 or newer. If needed, upgrade first with nvm install 22 && nvm use 22. Node.js 20 is end-of-life and is not a supported Hara runtime.

npm i -g @nanhara/hara

Or a standalone binary (no Node required):

curl -fsSL https://raw.githubusercontent.com/hara-cli/hara/main/install.sh | sh

Tab completion (optional): eval "$(hara completions zsh)" in your ~/.zshrc (or bash/fish).

Or in Docker — run hara against any repo without installing Node, and as an isolated/ephemeral environment (handy for CI):

docker run --rm -v "$PWD:/workspace" -e HARA_API_KEY=sk-... ghcr.io/hara-cli/hara -p "summarize this repo"
# interactive TUI:
docker run --rm -it -v "$PWD:/workspace" -e HARA_API_KEY=sk-... ghcr.io/hara-cli/hara
# or build it yourself: docker build -t hara . && docker run --rm -v "$PWD:/workspace" -e HARA_API_KEY=sk-... hara

Or from source:

git clone https://github.com/hara-cli/hara && cd hara
npm install        # builds via the prepare script
npm install -g .   # or: npm link

If a source checkout linked before 0.122.1 later reports zsh: permission denied: hara, the old npm link is still targeting the now-internal dist/index.js. Activate the same Node installation that owns the link, run npm link again from this directory, then run rehash. npm run build and npm run doctor:local-link detect this stale link and print its exact owning bin directory. Do not repair it with chmod; the guarded executable entry is runtime-bootstrap.cjs.

Quickstart

npm i -g @nanhara/hara
hara setup               # choose a provider, masked key, and model from a list
cd your-project
hara                     # offers to write AGENTS.md, then drops you into the TUI

Then just type a task — e.g. fix the null check in @src/login.ts and run the tests. shift+tab cycles approvals (incl. plan mode) · Esc interrupts · @+Tab attaches a file · /exit quits.

One-shot, no REPL:

hara -p "summarize @README.md and list any TODOs"

Setup

The fastest path is hara setup — an interactive wizard for provider + key + model (it also runs automatically the first time you start hara unconfigured). Or configure it yourself — hara is multi-provider:

Every hara profile add <name> --byok ... command creates an independent model connection. You can keep several providers—or several accounts from the same provider—with separate keys, endpoints, models, and reasoning defaults, then switch new work with hara profile use <name>. Existing sessions stay pinned to the exact connection they started with.

Anthropic (default)

export ANTHROPIC_API_KEY=sk-ant-...

Volcengine Ark Agent Plan — Codex/Responses route

hara profile add ark-agent-plan --byok \
  --provider volcengine-agent-plan \
  --model auto
# Enter the Agent Plan key at Hara's masked prompt, then:
hara profile use ark-agent-plan

Hara pins this provider to https://ark.cn-beijing.volces.com/api/plan/v3, reads ARK_API_KEY when no key is stored, and uses the Responses protocol documented for Codex. auto is the recommended quality/speed router; ark-code-latest remains available for compatibility with the model selected in the Ark console. Choose an explicit model id to pin a session. Hara keeps durable history local with store:false, filters non-conversation media models out of /model, and exposes the endpoint's native thinking controls. Agent Plan is licensed for supported interactive AI tools, not arbitrary backend API use. Direct Codex and Claude Code configuration, including their intentionally different endpoint/protocol, is documented in docs/volcengine-agent-plan.md.

Alibaba Model Studio Token Plan (recommended subscription route)

hara profile add tokenplan --byok \
  --provider token-plan \
  --model qwen3.8-max
# Enter the Token Plan key at Hara's masked prompt, then:
hara profile use tokenplan

/model reads the Key's live Token Plan catalog and hides image/audio/video generators that need their own API or Skill. Hara chooses the wire protocol per model on the shared endpoint: the documented Qwen 3.8/3.7/3.6, DeepSeek V4, and GLM 5.2 Token Plan models use Responses; unknown future/other entries conservatively use Chat until Alibaba documents Responses support. Normal chats expose Auto plus the model-supported thinking levels. Selecting Off sends Alibaba's explicit enable_thinking:false extension without a competing reasoning object, so the server actually stops generating reasoning tokens. Responses calls keep Hara's durable history local (store:false) and opt into Alibaba's Session cache header; Hara still replays its own verified history instead of depending on a response id that expires after seven days. Alibaba's provider-executed Harness tools are not silently added to a turn: Hara exposes its own audited tool surface so local approval, company policy, and execution logs remain authoritative. Existing Coding Plan endpoints remain available for legacy saved profiles, but new Token Plan Keys and Base URLs are isolated and cannot be mixed with them. For non-interactive setup, omit the stored key with --no-key-prompt and provide OPENAI_API_KEY only in the trusted launcher environment. Do not place a Token Plan key in Hara Control or another shared application backend: the subscription is licensed for interactive coding/agent tools, and each Key must stay paired with its Token Plan endpoint. Token Plan has no browser-login flow in Hara: the browser is used only to purchase the plan and manage its Key in Alibaba Cloud. hara login qwen remains a legacy Qwen Code compatibility command for existing users and is not shown as a new Token Plan connection.

Plan keys (Coding Plan / Token Plan) are licensed only for use inside AI coding agents / OpenClaw-type tools like hara — not Dify/n8n, API-testing tools, or direct script/backend calls.

MiniMax Token Plan — Codex/Responses route

hara profile add minimax --byok \
  --provider minimax-token-plan \
  --model MiniMax-M3
# Enter the MiniMax Token Plan key at Hara's masked prompt, then:
hara profile use minimax

Hara pins this preset to MiniMax's documented https://api.minimaxi.com/v1 Responses endpoint, keeps the address visible in settings, and offers the live Key-scoped model catalog with MiniMax-M3 as the bounded fallback. Adaptive Thinking is exposed as off/on, and the current MiniMax Codex model catalog declares native text and image input. A custom OpenAI- or Anthropic-compatible MiniMax endpoint remains available through the generic custom-provider path.

DeepSeek — native Responses for V4 Flash and V4 Pro

hara config set provider deepseek
hara config set apiKey   ...
hara config set model    deepseek-v4-flash   # the built-in default
# or: hara config set model deepseek-v4-pro

On the official https://api.deepseek.com endpoint, deepseek-v4-flash and deepseek-v4-pro use the semantic streaming Responses API. Hara resends the complete durable message/tool history on every request because this endpoint is stateless: it never depends on previous_response_id, conversation, or server-side storage. Explicit custom or legacy ids are not silently remapped; their availability remains provider-side. DeepSeek V4 Flash and Pro remain text-only, while deepseek-v4-flash-vision-exp accepts native image input. You can also keep Flash/Pro as the conversation model and explicitly use the vision model as the image pre-processor described below. If live model discovery is unavailable, /model still offers the three documented V4 models as a host-scoped fallback; a successful live /models response remains authoritative.

Any OpenAI-compatible endpoint (GLM, Kimi, OpenAI, local servers)

hara config set provider openai
hara config set baseURL  https://your-endpoint/v1
hara config set apiKey   ...
hara config set model    ...

Proxy for mainland/restricted networks — provider/model requests, organization enrollment and web tools can share one user-controlled HTTP(S) proxy:

export HTTPS_PROXY=http://127.0.0.1:7890
# or for one Hara launch (do not put credentials in command-line arguments):
hara --proxy http://127.0.0.1:7890
# or persist the same endpoint privately:
hara config set proxy http://127.0.0.1:7890

HTTP_PROXY, HTTPS_PROXY, lowercase variants, and NO_PROXY are supported. HARA_MODEL_PROXY targets model/provider and organization traffic; HARA_WEB_PROXY remains web-tool-only. On Windows, Hara also follows an enabled static WinINET system proxy (including its bypass list) when no explicit proxy is configured; PAC-only and SOCKS-only settings still require an explicit HTTP(S) proxy. Loopback models such as Ollama and LM Studio always bypass the proxy. Chat gateways are not silently redirected. Even through a proxy, web_fetch pins each DNS-approved public IP and rechecks redirects; authenticated proxy URLs and transport errors are masked.

When web_fetch receives only a JavaScript SPA shell, it tells the agent to retry with render:true. That path asks for computer-use approval, uses an installed Chrome/Chromium/Edge with a fresh temporary profile, and routes every browser request back through the same private-IP/redirect guard. Set HARA_BROWSER_PATH only when the browser executable is installed in a non-standard location.

Package registry for slow/restricted npm networks — switching is explicit, so Hara never sends a private scope to a public mirror without your decision:

hara --registry npmmirror             # this launch
hara config set packageRegistry npmmirror  # persist globally

The bash tool also accepts registry:"npmmirror" for one npm/pnpm/yarn/bun install. Use npmjs, npmmirror, or a credential-free HTTP(S) registry URL; keep private-registry authentication in the package manager's normal credential store. HARA_PACKAGE_REGISTRY is the environment equivalent.

Replies follow the latest user message's language by default. Use hara --lang zh-CN (or en) to pin one launch, and hara --lang auto to restore per-message matching.

Vision — by default, hara auto-detects whether the selected conversation model can see images and sends images inline only to a known multimodal model. To make a dedicated model handle all recognition first, enable the explicit vision-first route:

hara config set visionModel deepseek-v4-flash-vision-exp
# Optional for Personal/BYOK when vision is hosted elsewhere:
hara config set visionBaseURL https://api.deepseek.com
hara config set visionApiKey YOUR_VISION_KEY

Once configured, pasted images, Desktop/Serve attachments, inspect_image, and computer screenshots all go first to that model with only a focused transcription prompt. The main conversation model receives the resulting text and never the raw image—even when it supports vision itself. Use /vision to inspect the route, /vision <model> to change it, and /vision off to disable it. /vision main yes|no|auto still corrects native capability detection for custom models.

Company Spaces fail closed: the configured vision model must appear in that connection's administrator- advertised model list, and the image request reuses the managed gateway credential. A local setting cannot widen a company Key. Desktop exposes the same setting under Models & connections → Vision-first image recognition and never returns a saved key to the renderer.

Reasoning effort — choose from the levels the current model actually supports. Hara's internal vocabulary is off · minimal · low · medium · high · xhigh · max; binary and narrower providers expose only their valid subset, and an unset value keeps the provider/model default.

hara config set reasoningEffort high     # also off / minimal / low / medium / xhigh / max

hara expresses it the way each endpoint wants (OpenAI reasoning_effort, Anthropic thinking budget, DashScope enable_thinking, DeepSeek Chat thinking + reasoning_effort, or DeepSeek V4 Responses reasoning.effort). Alibaba Token Plan Responses uses reasoning.effort:none for Off because that object takes priority and enable_thinking is deprecated there. Its picker is model-specific: Qwen3.8 and GLM 5.2 expose all seven levels on the Beijing Token Plan endpoint, and each DeepSeek V4 variant exposes only its effective native subset. An endpoint rejection is surfaced instead of silently retrying with the provider's expensive default. DeepSeek V4 Flash, Pro, and Vision-Exp expose model-specific thinking grades; Vision-Exp also accepts native image attachments through Responses input_image. On DeepSeek Responses, Hara maps off to the documented none value without changing transport. The shared cross-provider medium value normalizes to DeepSeek high. In the TUI, bare /model opens a picker — ↑↓ pick a model, ←→ set the thinking level.

Config lives in ~/.hara/config.json; the nearest project .hara/config.json may set the explicitly safe project preferences model, theme, vimMode, autoCompact, and reasoningEffort. Repository config is untrusted by default: routing/credential, hook/MCP, approval/sandbox, computer-control, and other privileged keys are ignored with a key-name-only warning. For a repository you have reviewed, launch with HARA_TRUST_PROJECT_CONFIG=1 to enable all of its project keys for that process. The opt-in is captured at startup, and project config itself must be a bounded regular file under a real (non-symlink) .hara directory. Effective precedence for enabled keys is environment > project > selected overlay > global. Empty routing values are ignored, so an empty project/env value cannot hide a working global credential or endpoint. Env overrides include HARA_PROVIDER, HARA_MODEL, HARA_BASE_URL, HARA_API_KEY, and the provider key (ANTHROPIC_API_KEY / DASHSCOPE_API_KEY).

Use

hara                       # interactive REPL (offers to create AGENTS.md on first run)
hara init                  # analyze the project & (re)generate AGENTS.md
hara doctor                # check your setup (auth / model / node / assets / roles)
hara roles init            # scaffold role-agents (implementer / reviewer / docs)
hara roles                 # list Hara roles + compatible personal/project Claude Code agents
hara org "review src/ for bugs"   # dispatch a task to the role that owns it (or --role <id>)
hara projects add shop /absolute/path/to/shop   # register an agent home
hara agents                # list global + registered project agents
hara org --role shop:reviewer "audit auth"     # run that agent at its own home
hara plan "add a /health endpoint with a test"   # decompose → sequence (DAG) → run each step + verify
hara plan --parallel "..."  # run independent atoms concurrently  ·  hara plan resume  # continue a stopped plan
hara review                 # review uncommitted changes for bugs/security/missing tests (--staged · --base main)
hara commit                 # AI commit message from staged changes, then commit (-a to stage all · -y to skip confirm)
hara index                 # build the semantic search index (after: hara config set embedProvider ollama|qwen)
hara -p "summarize @README.md and fix the lint errors in src/"   # one-shot; @path attaches a file
hara -p "extract package metadata" --schema ./schema.json         # stdout is exactly schema-valid JSON
hara -p "review the current diff" --role reviewer                 # persona + model + tool policy from the role
hara --approval auto-edit  # suggest (default) | auto-edit | full-auto   (-y = full-auto)
hara --sandbox workspace-write   # confine shell writes to the project (macOS Seatbelt)
hara --cwd /path/to/project      # explicitly select a workspace without changing your shell directory
hara -c                    # resume the most recent session in this directory
hara --profile work        # use a named profile from ~/.hara/config.json
hara profile add work --gateway https://control.example.com --code <one-time-code>  # user-added org route
hara profile add custom --byok --provider openai-compatible --base-url https://provider.example/v1 --model model-id  # masked key prompt
hara -m glm-5              # pick a model

Run Hara from a project directory. When the current directory resolves to your Home root, Hara does not treat the whole Home tree as a repository: project init/index and default recursive grep/glob/codebase inventory are disabled with a cd /path/to/project / hara --cwd /path/to/project hint. Directory listing and child-directory recursion are also refused so the model cannot promote a discovered Home folder into an implicit project; explicitly named single files still work. Resuming a session reuses its persisted conversation and must not trigger workspace rediscovery.

For automation, --schema accepts inline JSON Schema or a schema file. The model must return through the validated structured_output tool; on success stdout contains only the JSON value, while diagnostics go to stderr and missing/invalid output exits non-zero. --role reviewer resolves locally, --role global:reviewer uses the portable global persona in the current project, and --role shop:reviewer runs at that registered project home. Each form enforces the role's persona, model, allowTools/denyTools, and readOnly policy.

Inside the REPL: /help /init /tools /model /approval /org /plan /roles /task /continue /new /evolve /usage /doctor /sessions /undo /compact /recall /reset /exit (type /+Tab to complete). /task shows the active execution record; /task clear drops it without deleting the conversation, and /new starts a new task while retaining useful thread context. Type @ + Tab to attach a file (fuzzy, walks subdirectories).

The interactive REPL is an ink TUI: a bordered input box pinned at the bottom — session name in the top-right corner, approval modes + token usage + concurrency in the bottom border — with the conversation scrolling above it. Streaming answers, tool calls, and colored diffs render as live blocks; provider reasoning never enters terminal or transcript state, while a typed phase and spinner show that the turn is active. shift+tab cycles the approval mode, Esc interrupts a running turn, and tool approvals appear inline (y/N). Ctrl+V pastes an image from your clipboard (a screenshot, or a copied image) — or drag an image file into the terminal — and it appears as a highlighted [Image #N] token inline where your cursor is (backspace over it to remove it). Without visionModel, a multimodal model sees the image directly. With visionModel, every image is described there first and the conversation model receives text only. A text-only route with neither option asks you to configure or switch models. Set HARA_TUI=0 for the classic readline REPL.

Text pasted by a modern terminal is handled as one bracketed-paste event, including multiline Claude/Codex output and a paste immediately followed by Enter. It is inserted for review and never auto-submitted merely because it contains newlines; malformed/incomplete frames are bounded and surfaced instead of hanging raw mode.

Each session gets a UUID and an auto-summarized name from your first message (kept verbatim, CJK included); hara sessions lists them by short id, and --resume <prefix> accepts the short id. When you refer to an older conversation, the agent can use session_search: it searches bounded user/assistant excerpts from prior sessions, excludes tool payloads and the active session, and keeps interactive, gateway, and cron audiences separate. Its default checks the current project first and, only when that has no match, makes one bounded fallback across other local interactive workspaces—so a cwd switch does not hide the immediately preceding chat. scope=project forbids that fallback; scope=all requests a broad interactive search. Every returned excerpt identifies its source workspace when needed and is treated as untrusted reference text rather than an instruction.

Durable memory remains a smaller curated layer: project facts/decisions default to project MEMORY.md, while target=user defaults to global USER.md. Exact duplicate facts/preferences are not appended again, and the agent cannot replace a whole memory file in one call. Chinese lexical queries return the matching part of a long file rather than its header. Because these Markdown files are editable and syncable, Hara re-sanitizes them on injection, retrieval, log distillation, and semantic indexing; unsafe lines and secret-shaped values never become trusted prompt or embedding input.

Execution-time learning is a separate reviewed ledger under private Hara state. hara learning list shows personal, project, and active-organization candidates with recurrence and revision evidence; approve|reject|revoke <id> controls local rules. An organization candidate must recur at least three times across two tasks in 30 days before hara learning submit <id> can send its already-redacted receipts to Control. Administrators approve or reject there, and hara learning sync pulls one versioned full bundle so revocations remove rules from prompt context. Raw conversations, credentials, user paths, and files are never stored in this ledger, and approval supplies context only—not tool authority.

Assistant output is rendered as Markdown (headers, bold, inline code, lists; code fences verbatim), and a model's reasoning shows dimmed before the answer when available. Both are interactive-terminal only; HARA_MD=0 disables Markdown rendering.

Skills — reusable capabilities on the agentskills.io standard (SKILL.md, interoperable with Claude Code / codex / openclaw). Drop a ~/.hara/skills/<name>/SKILL.md (or project .hara/skills/) with name + description frontmatter and Markdown instructions; the agent sees the list and calls the skill tool to load a skill's full body only when it's relevant (progressive disclosure). hara skills init scaffolds one, hara skills lists them, /skill <id> loads one into your next message, and the agent saves its own with skill_create (scope: project|personal). Optional frontmatter: when_to_use, allowed-tools, context: fork (run as a sub-agent), paths. allowed-tools is an engine-enforced exact allowlist, not a prompt hint: disallowed schemas disappear and retained/hallucinated calls are rejected at dispatch. Loading multiple restricted skills intersects their lists, so a later skill cannot widen authority. Hara keeps only its non-task safety helpers available. A forked skill that declares allowed-tools currently fails closed until the child-run policy receipt is wired. When the agent saves a skill, secrets are redacted and local paths/emails generalized (<project> / ~ / <email>), and a near-duplicate is flagged so it updates instead of piling up. assetCapture: off|ask|auto controls proactive end-of-session capture.

Plugins — bundle skills + roles + MCP servers in one installable unit (Claude-Code-compatible plugin.json / .claude-plugin/). hara plugin add file:<path> | github:<owner/repo> | git:<url> installs it; hara plugin lists; enable/disable/remove. A plugin's skills/roles/MCP auto-contribute (your project & global override them). Installation validates the full package in a private stage, activates it atomically, and records an owner-only receipt for the exact root and command links. Plugins installed before 0.126.1 remain usable; reinstall the same reviewed source once to create the receipt before removing them. .claude/agents/*.md subagents load as roles too.

Recall — hara recall --init creates a personal ~/.hara/code-assets library (snippets as *.md); hara recall "<query>" searches it plus your skills (one corpus), and /recall <query> pulls the best matches into your next message. A git-versionable library of code/patterns you want to reuse (HARA_ASSETS overrides the path).

Semantic search (opt-in) — codebase_search, recall, and memory_search can find things by meaning, not just keywords. By default they're lexical (zero setup). Configure an embedding provider, then build an index: hara config set embedProvider ollama (local & offline, e.g. bge-m3/nomic-embed-text) or qwen (DashScope), then hara index (repo, for codebase_search) / hara index --assets (code-assets, skills & memory) / hara index --all. A query like "read an image pasted from the clipboard" then surfaces src/images.ts even with no shared words. Indexes are rebuildable .hara/index/ artifacts (self-.gitignored, never committed); no native vector DB needed, and lexical still works when there's no index. Re-running hara index is incremental — only changed files re-embed (a full repo rebuild that takes ~a minute re-runs in well under a second).

Approval modes: suggest confirms edits & shell · auto-edit auto-applies file edits but confirms shell · full-auto runs everything. Choosing always for this project stores only an opaque grant digest in the owner-only ~/.hara/project-approvals.json: Bash binds to the exact command, ordinary file changes bind to one exact file, .tmp//logs//output/ bind to that one directory, and Python explicitly binds to Python execution in that project. The grant also binds to the real project directory identity, so deleting and recreating a path does not inherit it. Deny rules, protected-file checks, the guardian, Computer Use and external MCP/agent confirmations remain stricter and cannot be bypassed by a remembered grant. Protected files and shell sandboxing: built-in file, search, and context paths hard-reject .env/credential/private-key/private-Hara-state files before the ordinary approval/dispatch path can authorize them. Safe templates (.env.example, .env.sample, .env.template) remain readable. HARA_ALLOW_SENSITIVE_FILES=1 is an explicit one-process exposure switch: it removes these built-in denies and that process's shell protected-read mask. Shell subprocesses receive a scrubbed environment; explicitly retain a named inherited variable with HARA_SUBPROCESS_ENV_ALLOW=NAME[,NAME] (output is still redacted). With the protected-file policy enabled, shell preflight rejects literal protected paths and environment-dump commands on every OS. On macOS, Seatbelt also masks existing protected files/directories from the shell and --sandbox workspace-write|read-only provides file-write confinement. Linux/Windows have no equivalent kernel read mask: static shell preflight is a useful guardrail, not a security sandbox, and arbitrary code can bypass it. Screen control (opt-in): the computer tool drives desktop software (screenshot → click/type), native per OS (mac screencapture+cliclick · Windows PowerShell · Linux scrot+xdotool). Off by default — enable a tier with Desktop Settings → Security → Computer Use, or use hara config set computerUse read|click|full and allowlist apps with hara config set computerApps "App, …". Concrete browser/desktop requests receive this core tool on the first useful model round; after open_browser, it also becomes available automatically on the next round. Guarded by the tier, the frontmost-app allowlist, a dangerous-key blocklist, and per-action approval. Screenshots are read into actionable output—interactive elements + positions (pass focus to target what you're after)—by the configured vision-first model, or otherwise by the multimodal conversation model. A text-only route with neither option cannot perform visual screen control. The same Desktop card can explicitly install Hara's pinned, isolated structured-browser backend for accessibility-tree navigation, forms, uploads, and post-action verification; it does not reuse another browser's login state. Sessions and task execution: conversations are saved automatically — -c / --resume <id> or hara resume <id> to continue, hara sessions to list, hara export [id] [--out file] to render one as a Markdown transcript. The current task is persisted separately with stable task/turn identity and recovers as paused rather than being inferred from chat text. At idle, ordinary input starts a new task; an explicit 继续 / continue / resume / go on resumes the paused objective, while /new forces a clean task boundary. Type-ahead Enter steers the exact live turn; /next <message> queues a separate task after it. Current Desktop/serve clients use the feature-detected session.submit admission point: Core atomically starts an idle session or steers its authoritative live turn, serializes concurrent submissions in arrival order, and returns an explicit non-submission reason when attachments or a forced newTask must wait for the next turn. When Desktop has staged a model or thinking change, expectedModel + expectedEffort also keep an idle transition from starting that input on the previous provider configuration. For an accepted change task, Core owns execution: if an in-scope action is authorized, tool-supported, and risk-controlled, Hara must perform and verify it instead of ending with instructions for the user. A handoff is accepted only as a fresh structured dependency for a missing secret/authority, unavoidable physical action, material choice, external state, or destructive confirmation, with observed evidence shown by Desktop. Older protocol-v1 clients remain compatible through strict session.send and expected-turn session.steer; accepted steering is durable before ACK. The hara resume launcher preserves terminal input in both npm/Node and standalone-binary installs. Local deliverables: Hara Serve 0.128 adds the first local artifact/1 foundation for presentations, spreadsheets, and documents. An authenticated Desktop client can import, list, integrity-check, and inspect version history through artifact.import|list|get|revisions. The next revision transaction slice also advertises artifact.commit|revert: every edit supplies the version it started from, a stale edit fails with an explicit conflict, and reverting creates a new immutable revision instead of rewriting history. Import and commit make owner-only copies under ~/.hara/artifacts, never change the selected source file, and never store its absolute path. Relative, linked, protected, macro-enabled, type-confused, empty, and oversized inputs fail closed. The runtime does not yet render, format-edit, export, or execute imported content; those operations require matching reviewed Office capabilities and validation/export receipts. MCP: add an mcpServers map to global config (a reviewed project config additionally needs HARA_TRUST_PROJECT_CONFIG=1 at launch). Each entry may include a short non-secret description (for example, "Bilibili fan queue status updates") so the model can select the right server while it is still stopped. Hara starts with every configured server stopped and exposes only mcp_connect; when the current task first needs one server, the agent requests permission to connect that server and its tools appear on the next round as mcp__<server>__<tool>. Unrelated servers remain stopped. Configured MCP servers, like external_agent, are trusted host extensions outside Hara's protected-file boundary. Every interactive external-tool call requires confirmation (even in full-auto), and non-interactive runs disable them by default; reviewed automation can explicitly opt in before launch with HARA_ALLOW_TRUSTED_EXTENSIONS=1. hara can also be an MCP server — hara mcp exposes its read/search tools (esp. codebase_search) over stdio so other clients (Claude Desktop, Cursor, another hara) can use them; read-only by default (HARA_MCP_TOOLS to override). Vim mode: hara config set vimMode true makes the prompt modal — Esc → normal, i/a/A/I insert, h l 0 $ w b e motions, x D C dd cw p edits. Off by default. Scheduled tasks: hara cron add "0 9 * * 1-5" "<task>" (or "every 30m", "in 2h") runs a task on a schedule — each run is a fresh hara session. hara cron install wires a per-minute tick into calendar-minute launchd events on macOS or crontab on Linux (no daemon); --org routes through the role org. macOS users upgrading from Hara 0.134.1 or older should run hara cron install once to replace the old coalescible StartInterval LaunchAgent; jobs and run history are preserved. Manage with hara cron list/run/enable/disable/remove/logs. Every job has a 30-minute deadline and the whole sequential tick has a non-renewable 60-minute watchdog: a job timeout kills its process tree, records timed out + duration/error, then continues with the next due job; a tick timeout stops the remainder and releases the global lock. Add --deliver feishu:<chatId> (or Telegram/WeChat/webhook) for outcomes. --deliver-mode always preserves the existing every-run heartbeat, on-output sends only when redacted stdout is non-empty, and on-error sends only failed runs; --alert-after N remains independent and still raises the consecutive-failure 🚨 threshold alarm (default 3). Delivery intent is durable before transport, uses a stable idempotency key, and retries with bounded backoff on later ticks until confirmed. A failed channel cannot grow jobs.json forever: each job keeps at most 64 pending effects, reserves outcome/alert room before launch, and disables itself with a visible backlog error when full; restore delivery, let the queue drain, then re-enable it. Tune milliseconds with HARA_CRON_JOB_TIMEOUT_MS (hard max 24h) and HARA_CRON_TICK_TIMEOUT_MS (hard max 5h); scheduled jobs are also capped by the tick. After upgrading from a version whose tick is already stuck, terminate that specific legacy hara cron tick process tree once (or reboot); the next scheduler minute marks over-age state interrupted/disabled and recovers the lock without replaying a possibly orphaned task. Work coordination: todo_write is the agent's short, session-scoped checklist; it persists with that session and is isolated between simultaneous sub-agents and serve sessions. task is the durable project pool for work that outlives a conversation: add/update/list/remove items with pending|in_progress|done, an optional owner, and blockedBy dependencies. The private, atomic store is shared by concurrent hara processes for the same project and rejects missing/self/cyclic dependencies. Conversation and execution: the composer first routes an input as a local control, a new task, a steer of the exact live task, or an explicit next task. User-invocable slash Skills are executable turns and accept live steering; local controls such as /model are serialized without pretending to own a task. A main task keeps the raw user request and a separate accepted brief (intent, interpreted goal, constraints, acceptance checks, and steps). Hara permits read-only investigation before that brief, but its engine blocks side effects until the understanding has been checkpointed in its own model/tool round. Mixed tools are classified by action (task list is a read), and a brief revision cannot share its round with a side effect. /task shows the current execution identity and brief. See docs/conversation-task-execution.md. Notifications: hara config set notify bell (terminal bell) or notify system (OS notification) pings you when a turn finishes — handy for long runs you've stepped away from. Gated on elapsed time so quick turns stay quiet; off by default. Run limits and loop alarms: every agent turn has a non-renewable 30-minute active-execution budget and a 64-round model/tool cap. Time spent waiting for an engine-owned question or approval does not consume that budget; the status row says the task timer is paused, while Esc, shutdown, and explicit cancellation still take effect immediately. Answering resumes the remaining budget rather than resetting it. Hara warns after five active minutes or at 75% of the round budget, stops after one unchanged retry of an identical failing tool call, and surfaces the final reason in CLI, Desktop, or gateway output. Tune intentional long work with hara config set runTimeoutMs 45m (1s..2h) and hara config set maxAgentRounds 96 (1..256), or HARA_RUN_TIMEOUT_MS / HARA_MAX_AGENT_ROUNDS; neither boundary can be disabled. A main task with a recent durable checkpoint and fresh evidence may cross an ordinary numeric round boundary into another bounded tranche automatically. Disable that behavior with hara config set autoContinue false or HARA_AUTO_CONTINUE=0; the active deadline, unchanged-evidence guards, cumulative task checkpoints, and absolute run/task ceilings still apply. Empty, pre-output rate-limit, overload, timeout, and transient provider failures use a central three-attempt replay-safe policy that schedules retries only within 60 seconds and never retries earlier than a bounded Retry-After; Hara never retries after any stream activity, text, tool call, or output token. Sub-agents are capped at 8 minutes/24 rounds and inherit the parent's cancellation. Auxiliary model work (planning, verification, compaction, naming, commit messages, the guardian, and vision) has its own short hard deadline as well, so a provider that ignores cancellation cannot strand the CLI outside the main loop. Hooks: run your own shell commands around tool calls via a "hooks" map in global config; hooks from a reviewed project config require the launch-time HARA_TRUST_PROJECT_CONFIG=1 opt-in. A PreToolUse hook can veto a call (non-zero exit blocks it; its output becomes the reason the model sees) — gate bash, forbid edits outside a path, require a clean tree. A PostToolUse hook observes (format/lint a file the agent just wrote, log, notify). Each has a matcher (regex/literal on the tool name, * = all) and gets {tool, payload} on stdin + HARA_TOOL_NAME in env. Plugins can contribute hooks too. Reviewer/read-only/plan runs and parallel read-only sub-agents suppress both hook phases: PreToolUse and PostToolUse commands are arbitrary shell, so either could otherwise bypass their read-only contract indirectly. They also omit the lazy connector for configured and plugin-provided MCP servers, so a read-only role cannot start an external tool server. Profiles and live config: select an identity with --profile <name>; use overlays in ~/.hara/config.json for named config overlays. Project .hara/config.json files get the safe preference allowlist above; project-specific routing requires HARA_TRUST_PROJECT_CONFIG=1 before launch. Organization connections are never prefilled: add one with hara profile add <id> --gateway <https-url> --code <one-time-code> or in Desktop's AI & models settings. The registration code is exchanged once and discarded; only the scoped, revocable device credential is retained in the private ~/.hara/profiles.json. One Hara Control connection can advertise multiple authorized models; users switch among them without changing its Token. An authenticated heartbeat refreshes that catalog in place, while expiry and quotas remain attached to the same connection. .hara-profile identity pins are read no-follow with size, single-inode, and hard-link checks; pin updates use an atomic compare-and-swap, and invalid-pin warnings never echo file contents or paths. A Git-tracked pin is repository-controlled and ignored by default; local untracked pins created with hara profile pin work normally. The same launch-time HARA_TRUST_PROJECT_CONFIG=1 opt-in enables a reviewed tracked pin. Long-lived hara serve processes reload provider credentials/routes and guardian settings for the target cwd on new sessions and turns. models.list and new sessions see current defaults; every new session persists both its model and identity profile, and resume keeps that exact route even if another enterprise connection becomes active later. That binding includes heartbeats, managed-role sync and prompt catalogs, guardian checks, subagents, and auxiliary model routes; managed role bundles are stored separately for each enterprise profile. Credential rotations for the same profile take effect without restarting the server, while a removed, expired, or unauthorized profile fails closed instead of silently moving an old conversation to another organization or Personal.

The org — what makes hara different

Define role-agents in .hara/roles/*.md — each is a private persona (the file body) plus frontmatter: owns (keywords that route a task here), optional rejects, model, allowTools/denyTools, and a bounded public profile (display-name, title, bio, traits, emoji, avatar, identity-theme, accent, character). hara org "<task>" routes the task to the role that owns it (keyword match, LLM fallback) and runs that role's agent — e.g. a read-only reviewer that reports issues vs an implementer that edits code. hara roles lists them, hara roles init scaffolds a starter set, and --role <id> forces a specific role. Add --review and the org works like a team: the owning role implements, then a reviewer role inspects the diff and either approves or sends it back with fixes — looping implement → review → fix until approved (or --rounds N). Add --commit and it commits the approved result with an AI-written message (guarded to a clean start tree; a review that doesn't pass leaves the work uncommitted). The agent tool spawns parallel read-only sub-agents for fan-out — analyze / review / search several things at once (each can take a role). A provider-neutral root runtime owns FIFO admission, structured completion/cancellation/error state, and a bounded queue; the native provider keeps each child on an isolated checklist and read-only tool floor. Concurrency defaults to 8 (HARA_MAX_CONCURRENCY), and delegated token totals count toward usage without changing the parent conversation's context gauge. Persistent Serve/Desktop sessions also expose a durable Agent tree with idempotent mailboxes and whole-tree ceilings derived conservatively from the current saved connection's model capability. A child is still read-only unless spawn_agent explicitly requests workspace: isolated-write; that mode edits a private detached Git worktree and returns one owned Diff. apply_agent_diff always requires fresh human approval, rejects a moved base or overlapping source edits, and never auto-merges; reject_agent_diff leaves the source checkout unchanged.

OpenClaw and Hermes identities work in place too. Hara reads the installed OpenClaw Agent registry, maps each workspace's IDENTITY.md (plus safe local avatar) into the public Agent directory, and keeps SOUL.md/AGENTS.md private until that Agent is selected. A personal Hermes SOUL.md appears as a Hermes Agent with the same private boundary. Remote avatar URLs are never fetched automatically. Hara does not import provider keys, channel bindings, user memory, sessions, or credentials from either tool.

Claude Code role collections work in place: Hara discovers both ~/.claude/agents/*.md and project .claude/agents/*.md, translates common Claude tool names (Read, Edit, Bash, WebSearch, …), and treats Claude aliases and Claude-only model ids as “inherit the current Hara model” (a role cannot silently switch the active provider). Precedence is plugin < installed interop identity < managed org < personal Claude < personal Hara < project Claude < project Hara. Ordinary Hara turns receive only a compact, guarded catalog of role names and descriptions; a role's full prompt is loaded only after that role is selected. This lets the main agent ask an architect, debugger, tester, or reviewer for bounded independent analysis without copying every prompt into every request. Claude prompts that declare themselves workflow-only or require a private notification server / Claude-only local skill are automatically kept explicit-only; they remain available through --role / agent(role) but cannot be picked by automatic routing. Set disable-model-invocation: true to make the same boundary explicit for any other host-coupled role.

Register project homes with hara projects add <name> <absolute-path>, then hara agents becomes a global address book across ~/.hara/roles and each registered project's roles. A qualified address such as shop:reviewer is unambiguous; both hara org --role shop:reviewer "<task>" and one-shot hara -p "<task>" --role shop:reviewer execute at that agent's home, with its own AGENTS.md, live project config, role model, and allow/deny/read-only tool policy. A native global:<name> is portable and runs in the current project; an imported OpenClaw global keeps its declared Agent workspace. A bare name uses the local role first and otherwise must resolve unambiguously.

Beyond routing, hara plan "<task>" makes the org plan: it decomposes the task into atoms, sequences them as a DAG, and executes each step (optionally routed to a role) behind a per-step verify gate — frame → atomize → sequence → execute → verify. Each atom may carry a check shell command, so verification is objective (e.g. npm test, tsc --noEmit) rather than a self-assessment. Plan state is the SSOT at .hara/org/plan.json (inspectable; execution stops on the first failed verification — fix it and hara plan resume continues, skipping the atoms already done). With hara plan --parallel, independent atoms (the same dependency wave) run concurrently — the org works the independent parts at once, not one step at a time. The planner sees each automatically-invocable role's bounded description and read-only status—not only its id—so it can assign the right specialist and will discard a hallucinated, removed, or explicit-only role instead of silently running the atom as a generic agent.

What it can do

A streaming agentic loop with built-in tools — read_file, write_file, edit_file / apply_patch (surgical edits — single file, or atomic multi-file changes), direct-stdin python (one-shot APIs without helper scripts), bash, and read-only grep / glob / ls / web_fetch — behind a human-in-the-loop confirmation gate on the dangerous ones unless -y. Read-only tools run in parallel within a turn, and edits print a colored diff of what changed. Shell output streams live; press Esc to interrupt a running turn, or /undo to revert the last edit. In-session /diff, /review, and /commit close the change → review → commit loop without leaving the prompt.

• Explicit live steering vs next-task queue: keep typing while hara works and press Enter to fold a clarification into the next model call; use /next <message> to queue a separate task behind the live one. Accepted Desktop steering is persisted before ACK; Esc drops the local queue and stops.
• Bounded context + checkpoint compaction: each provider call receives a non-destructive budgeted snapshot (old tool payloads/images cannot monopolize context). Overflow retries once with a tighter snapshot; /compact creates a structured execution checkpoint and retains the latest three user-turn groups plus current touched-file content. Auto-compaction is on by default for terminal, headless resumed sessions, and Desktop/Serve after a completed turn reaches either 85% of its model window or the bounded absolute token cap. Serve also checkpoints oversized durable history before retrying after a failed turn, when no successful token watermark exists; hara config set autoCompact false opts out without removing manual compaction.
• Project context: auto-loads AGENTS.md (the cross-tool standard) walking up to the repo root; hara init writes one by analyzing the repo.
• @file mentions: attach file contents to a message (@path); Tab-completes with a fuzzy matcher over the project (subdirs, git-tracked + untracked) — @idx → src/index.ts. @<dir> loads a directory listing, @src/+Tab drills into a folder, and mistyped tool/file paths get a "did you mean" suggestion.
• Explicit workspace boundary: launching at Home does not inventory its directories or permit coding mutations. Start Hara from a concrete project, or pass hara --cwd /path/to/project, to enable search, @ completion, shell/external agents, and file edits; explicitly named single-file reads remain available at Home.
• Multi-provider: Anthropic (Claude) or any OpenAI-compatible endpoint (Qwen/DashScope, GLM, Kimi, OpenAI) — all streamed live.
• Chat gateway: drive your local hara from Telegram · WeChat · Discord · Feishu/Lark · Slack · Mattermost · Matrix · DingTalk · WeCom · Signal. The daemon connects out (no public webhook), with per-chat sessions, project roaming (/cd), agent switching (/agent), and two-way images on byte-upload-capable platforms. Setup, platform capability details, and the group-flow security model: docs/gateway.md.

Roadmap

Shipped: ink TUI · plan mode · persistent memory + self-evolution · atomization planner · parallel plan atoms · multi-role review chains · global project-agent index · durable project tasks · parallel sub-agents · MCP client and server · scheduled tasks (hara cron) · chat gateway (10 platforms, capability-aware media) · single-binary distribution · Docker image · /compact context management. Next: SSOT data authority · an enterprise control-plane (fleet + central token management).

Security

Human-in-the-loop by default, with a layered model (approval gate · read-only sub-agents · write-confinement sandbox · web_fetch SSRF guard · 0600 secrets · reviewed plugin trust). Threat model, controls, and how to report a vulnerability: SECURITY.md.

License

Licensed under the Apache License 2.0 (LICENSE) — a permissive license with an explicit patent grant. Contributions per CLA.md.

© 2026 Nanhara