Your agents do valuable work. Actanara makes sure it does not disappear with the session.
Turn sessions, tasks, and evidence from Codex, Claude Code, Gemini CLI, OpenClaw, and Hermes into local assets you can find, reuse, and revisit.

Try the Interactive Dashboard · Install Actanara · Operations Runbook

_{Real local Dashboard · select the image to explore the interactive demo}

What Actanara gives you

In a single project you might rotate through Codex, Claude Code, Gemini CLI, and other agents within a day. Each tool faithfully records your work—yet the records stay isolated from one another, and once a session ends the investigation, decisions, and results become hard to recover.

Actanara breaks down those barriers: work completed in Claude Code can be found and reused by Codex, scattered sessions become long-term reviewable progress, and deliverables and debugging evidence no longer vanish with a session.

	Outcome
Shared memory across agents	Work completed in Claude Code can be found and reused from Codex through a restricted, read-only retrieval boundary.
A graph of work that actually happened	Nova-Task derives tasks, status, and evidence from conversations, file changes, and tool results—not just manually written tickets.
Automatic work narratives	Daily, weekly, and monthly reports turn fragmented sessions into a durable record of progress, decisions, and lessons learned.
A local source of truth	Sessions, usage, generated assets, and task evidence remain in user-controlled local storage with explicit integration boundaries.

Design tradeoffs

• Parser-first processing: Source-specific parsers normalize sessions, tasks, usage, and workspace signals before data enters summarization, task-evidence, or RAG workflows. Raw logs are not handed directly to an LLM.
• Local-first with explicit boundaries: Actanara reads configured tool locations and writes to its own runtime home. It does not rewrite external-runtime history or take over runtime execution.
• Model-cost efficient: Structured prompts, explicit schemas, and controlled orchestration let lightweight models produce useful output without locking the system to one provider.
• User-controlled integrations: Tool skills, external-runtime definitions, and critical settings remain visible, editable, and auditable.
• Protected Agentic RAG: nova-RAG manages retrieval quality through evaluation, candidate promotion, recall calibration, and safe rollback, while exposing only a restricted read-only contract to external runtimes.

In this README, an agent runtime means an AI tool environment with its own sessions, logs, memory, and execution context, such as Codex, Claude Code, Gemini CLI, OpenClaw, or Hermes.

Install Actanara

curl -fsSL https://raw.githubusercontent.com/Neo-Isshin/actanara/main/install/setup.sh | sh

This is the shared macOS/Linux entrypoint and requires no sudo. It resolves the current official main to an exact commit before dispatching to the platform adapter. macOS keeps its guided fresh-install and update behavior; Linux supports guarded fresh install, source-only refresh, locked dependency upgrade, and confirmed repair of an existing Runtime. Linux update transactions preserve the prior systemd user-unit state and fail closed on definition drift or non-Actanara units. New here? You can explore the interactive Dashboard demo before installing.

The stable Runtime shim is ~/.actanara/bin/actanara; installation also links ~/.local/bin/actanara by default. On macOS, --no-shell-path and --shell-path-file /path/to/profile control the managed profile block. On Linux, --no-shell-path suppresses the user-bin link and no shell profile is edited. Advanced source selection uses --source-root PATH or an exact --ref <full-commit-sha>; offline operation must explicitly select one of those sources.

For the exact write locations and launchd/systemd registration boundaries, see the Local Operations Runbook.

🎥 Quick Start

Tip

Deploy with one command, then let prosperity follow.

1. Basic Verification

After installation, run these read-only commands first. They do not initialize a new runtime or change existing settings:

actanara doctor
actanara model show
actanara onboard status
actanara config show

actanara doctor also supports targeted diagnostics (--installer / --pipeline / --scheduler / --rag); see the Runbook for details. The installation summary displays the actual Dashboard URL; the default is http://127.0.0.1:3036/dashboard.

2. Complete the First Run

1. Open the Dashboard: Use the URL in the installation summary and check the background-task and message indicators in the upper-right corner.
2. Configure the LLM Provider: Verify the Provider, Endpoint, Model, and API Key. Run the availability test before saving.
3. Preview the historical-data plan: Select a date range and review pending diaries, weekly and monthly reports, and estimated LLM calls.
4. Queue generation: Clear any tasks you do not need, then add the remaining work to the background queue.
5. Review results: Monitor progress in Background Tasks and Messages. When complete, refresh Diary, AI Assets, Nova-Task, and optional nova-RAG views.

First-run checklist

• The Dashboard opens successfully.
• The LLM Provider test passes and the settings are saved.
• actanara doctor reports no blocking errors.
• The history plan and selected tasks match expectations.
• The first tasks have completed or are observable in the background.
• Diary, AI Assets, and Nova-Task contain data.
• When nova-RAG is enabled, the Server and active index are ready.

For complete pre-install checks, first-run setup, historical backfill, daily operations, updates, and troubleshooting, see the Local Operations Runbook.

🧭 How It Works

Supported Agent Runtimes
        ↓
Parsing, Attribution, and Normalization
        ↓
Foundation Local Fact Layer
        ↓
Base Pipeline · Nova-Task · Dashboard
        ↓
nova-RAG (optional) → Read-only Retrieval for External Runtimes

System	Core responsibility
Foundation	Normalizes AI activity, workspace attribution, snapshots, reports, and task evidence into a local fact layer.
Base Pipeline	Generates diaries, technical progress, learning records, and task summaries from runtime activity.
Dashboard	Presents diaries, AI assets, token usage, settings, background tasks, and task boards in one place.
Nova-Task	Maintains a reviewable task graph based on evidence from real work.
nova-RAG	Optional local- or cloud-embedding retrieval subsystem with a protected index lifecycle and external read-only retrieval.
Attribution Parsers	Identify runtimes, sessions, workspaces, scheduled jobs, and execution evidence, including work launched outside project directories.

💻 Support and Prerequisites

• 🍎 macOS remains first-class: Guided installation, updates, local nova-RAG, Dashboard services, and managed scheduling retain their existing user-level LaunchAgent behavior.
• 🐧 Linux has an explicit Core boundary: Fresh installs are available for Debian-class systemd --user hosts on x86_64 and arm64 lock targets, including cloud or CPU-only local-embedding RAG. Guarded upgrade/repair is release-gated on Debian x86_64 with CPython 3.13; the guided wizard and managed-Python bootstrap remain macOS-only.
• 🛠️ Base tools: Requires git and curl, plus zsh on macOS or POSIX sh on Linux; no sudo.
• 🐍 Python: macOS supports Python ≥ 3.11 and can install a verified managed Python; the audited Linux lock currently targets CPython 3.13.
• 🌐 Network and storage: Installation needs access to GitHub, the Python package index, and your model services; the first local nova-RAG run may download model weights.
• ⏱️ Linux services: Dashboard, scheduling, and optional RAG use user-level systemd units. When a controlling terminal is available, the installer asks whether they should continue after logout before making a no-sudo linger request. Non-interactive installs preserve linger unless --enable-linger or --require-linger is explicit.
• 🪟 Windows: Not a supported one-line target; some components can still be run from source by advanced users.

Currently supported agent runtimes: 🦞 OpenClaw · ✳️ Claude Code · 🤖 Codex · ✨ Gemini CLI · ⚕️ Hermes. What can be collected depends on whether compatible logs exist locally and whether their paths are enabled; additional runtimes and broader cross-platform support are planned for future releases.

📊 Dashboard, Screenshots, and Interactive Demo

The Dashboard is Actanara's primary operating surface: daily, weekly, and monthly diaries; live overview with token usage and AI-asset metrics; Foundation operations and data repair; background tasks and messages; LLM Provider and scheduling settings; the Nova-Task board with evidence review; and, when RAG is enabled, semantic search and retrieval-quality views.

🖼️ Real Dashboard Screenshots

The screenshots below come from the real Actanara Dashboard during development and operation, preserving the project's own design and components.

Expand the Dashboard home

Expand the W27 weekly report

Expand the AI Assets overview

Expand the Nova-Task work graph

Expand the nova-RAG status and retrieval interface

▶️ Interactive Demo

The Dashboard Static Demo preserves the real Dashboard HTML, CSS, and interaction code, replacing only backend APIs with static data, so it never connects to or modifies your local runtime. The version-controlled snapshot is also available at docs/dashboard-demo/index.html and can be opened from a local checkout.

▶ Open the Real Dashboard Static Demo

Common Commands

# Search local memory through nova-RAG (automation consuming JSON should check the available field)
actanara search "deployment issue" --top-k 5

# Run the daily Pipeline manually (defaults to the previous calendar day; --force regenerates)
actanara pipeline
actanara pipeline 2026-07-12

# Review or apply an update (default only shows the plan; --apply executes the protected transaction)
actanara update
actanara update --dry-run
actanara update --apply

When dependencies are unchanged the updater reuses the venv; otherwise it rebuilds from the hashed lock. Details on venv reuse, --source-only/--force-rebuild/--offline, source acquisition, and commit pinning are in the Runbook's Update section. Actanara does not yet ship a one-command uninstaller—do not remove only ~/.actanara; see the Runbook's Uninstall boundary section.

On Linux, ordinary updates require aligned Actanara-managed systemd definitions and preserve each unit's prior enabled/active state. If trusted Runtime configuration or managed definitions have drifted, use the explicitly confirmed repair path described in the Runbook; repair never adopts or removes an operator-owned unit.

📋 Nova-Task: A Graph of Real Work

Nova-Task is more than another to-do list. Much valuable work does not begin with a formal ticket but grows naturally through discussion, investigation, repair, experimentation, rollback, and verification—it converts those traces into a reviewable, maintainable task structure.

In automatic-maintenance mode, Nova-Task can detect hierarchy, update status, attach subtasks, and refine the task tree: high-impact top-level nodes retain human review, while routine updates proceed under configured rules, and a person can take over at any time. After an RFC, PRD, or Roadmap is imported, Actanara can also ask an LLM to decompose it into an iterative task tree. See Nova-Task Work-Graph Reconciliation.

🤖 nova-RAG: Shared Memory with a Read-Only Boundary

nova-RAG is Actanara's optional retrieval subsystem with local or cloud embeddings. It gives external agent runtimes read-only access to your work memory—they can retrieve it, but cannot write memory, change the index, alter settings, or control the service lifecycle.

Retrieval quality is managed at two levels: the server runs a deterministic, baseline-first adaptive pass, and only when it returns weak or ambiguous evidence does the external runtime's own LLM reflect further. nova-RAG also manages recall quality through query evaluation, candidate promotion, a protected index lifecycle, and safe rollback. For the complete read-only API, request schema, and error semantics, see the nova-RAG External Agent Runtime Contract.

🔐 Privacy and Security

• Local-first: Runtime state, the database, generated assets, and indexes remain in user-owned local paths.
• Secret permissions: Provider keys live in $ACTANARA_HOME/state/secrets; the directory uses mode 0700, and secret files use mode 0600.
• External-provider boundary: When an external LLM or embedding provider is configured, relevant content is sent according to the selected endpoint and provider data policy.
• Input becomes output: If source logs or materials already contain secrets or sensitive information, generated diaries, reports, and indexes may faithfully preserve them.
• Non-invasive boundary: Actanara does not rewrite supported runtimes' historical data or take over their execution. It creates only its own runtime, CLI shim, optional skills, and managed services.

📐 Development, Testing, and Reproducible Releases

Expand development and test commands

Create a local editable development environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dashboard,rag-local]"

Run the release suite with isolated virtual environment, HOME, ACTANARA_HOME, and a fixed business clock:

python tests/run_isolated_release_suite.py

Run deterministic frontend and Release Page tests:

npm ci
node --check src/dashboard/app/static/js/app.js
npm run test:dashboard-live-context
npm run test:release-page

Reproduce release artifacts for the current checkout:

python -B -m pip install -r requirements-release.txt
PROJECT_VERSION="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)" \
python -B -m tools.release.build_release \
  --source-root . \
  --output-dir ../actanara-release-artifacts \
  --expected-commit "$(git rev-parse HEAD)" \
  --expected-version "$PROJECT_VERSION"

The release builder accepts only a clean, committed Git worktree and writes output outside the repository. Artifacts include source and runtime-payload manifests, a normalized runtime archive, wheel, sdist, provenance, and SHA256SUMS.

📄 Documentation

User and Daily Operations

• ⚙️ Local Operations Runbook
• 📖 New User Onboarding Runbook
• 🧭 CLI Product Boundary

Integration and Product Design

• 🤖 nova-RAG External Agent Runtime Contract
• 🧩 Nova-Task Work-Graph Reconciliation

Release, Security, and Project History

• ✅ Release Assurance Archive
• 🧹 Production Cleanup Inventory
• 🧾 Changelog
• 🔐 Security Policy
• 🕰️ Public Project History

⚖️ License

Copyright © 2026 Neo-Isshin.

Actanara is free software licensed under the GNU General Public License, version 3 or any later version, with SPDX identifier GPL-3.0-or-later.

🙏 Acknowledgements

Actanara exists thanks to outstanding AI coding tools and their open-source communities. Their local activity and token-usage logs make unified visualization, asset consolidation, and cross-runtime memory sharing possible. Thanks also to the getdesign.md community for inspiration on the Dashboard's layout and visual direction.

---

⭐ Give me a Star

If Actanara helps you turn fragmented AI work into searchable, reusable local assets,
please give it a Star so more people can discover the project.