A personal AI assistant framework. Provider-agnostic. Clear architecture. Your data stays yours.

v0.2.2 — Core infrastructure plus session memory. Shaka sets up your environment, injects context into AI sessions, validates tool usage for security, summarizes sessions for cross-session memory, and works with both Claude Code and opencode.

git clone https://github.com/jgmontoya/shaka.git
cd shaka
bun install
bun link
shaka init

shaka init will detect your installed providers (Claude Code, opencode, or both) and set everything up.

Prerequisites: Bun and at least one of Claude Code or opencode.

Shaka doesn't replace your AI coding assistant — it enhances it. Once installed, it works invisibly through hooks:

1. You start a session (Claude Code or opencode). The SessionStart hook loads your identity, preferences, goals, and reasoning framework into the conversation context. The AI knows who you are and how to think.

2. You work normally. Type prompts, ask questions, write code. Shaka is transparent.

3. The AI tries to run a command. The security-validator hook intercepts it, checks the command against your security patterns, and blocks anything catastrophic before it executes.

4. You want to customize. Copy any file from system/ to customizations/ and edit it. Your version takes priority. Upgrades never touch your files.

That's it. No new UI to learn, no new commands to memorize. Shaka makes your existing tools smarter.

Inspired by PAI, Ren, and openclaw, but with a focus on:

1. Deterministic First — Do as much as possible in code before involving the model
2. Local First — No telemetry, no required cloud services, works with local models
3. Incremental — Ship working software at each phase
4. Extensible — Easy to add tools, skills, and agents
5. Clear Boundaries — Templates vs user files are never confused

1. Bun is the committed runtime -- No abstraction layer around Bun APIs. Services use Bun.file(), Bun.spawn(), etc. directly.
2. Hooks are standalone scripts -- Run directly with bun, no CLI binary required at runtime.
3. Content is declarative -- Markdown files, JSON config, YAML patterns. Code only where determinism is needed.
4. Dependencies at root level -- defaults/ is pure content. No node_modules/ inside it.
5. Both providers are first-class -- Claude Code and opencode supported from day one, not one primary + one afterthought.

For the rationale behind key structural decisions, see Architecture Decisions.

~/.config/shaka/              # XDG-compliant, provider-agnostic
├── user/                     # YOUR content (flat, portable, backed up)
│   ├── user.md               # Who you are (name, timezone, handles)
│   ├── assistant.md          # How your assistant behaves
│   ├── missions.md           # High-level purpose (TELOS-lite)
│   ├── goals.md              # Specific objectives
│   ├── projects.md           # Active projects and paths
│   └── tech-stack.md         # Preferred technologies
│   └── ...                   # Add more files as needed, these are auto-loaded at session start
│
├── memory/                   # What Shaka LEARNS about you (dynamic)
│   └── ...                   # Security logs, patterns (search TBD)
│
├── customizations/           # Your OVERRIDES for system/
│   └── base-reasoning-framework.md  # (example) Your reasoning variant
│   └── hooks/                      # Your hooks
│   └── ...
│
├── system/ → <repo>/defaults/system  # Symlink to framework (replaced on upgrade)
│   ├── base-reasoning-framework.md   # Default reasoning framework
│   ├── hooks/                # Event-driven automation
│   ├── skills/               # Reusable playbooks (markdown)
│   ├── tools/                # Deterministic operations
│   └── agents/               # Specialized personas (markdown)
│
└── config.json               # Configuration file

User file loading: All .md files directly under user/ are automatically loaded into the AI's context at session start by the session-start hook. Files in subdirectories (e.g., user/projects/details.md) are not auto-loaded — they must be explicitly referenced so the model can load them on demand.

When Shaka upgrades, system/ is re-symlinked to the new version. Everything else is preserved.

Files in customizations/ override their system/ counterparts:

customizations/base-reasoning-framework.md  →  overrides  →  system/base-reasoning-framework.md
customizations/hooks/session-start.ts       →  overrides  →  system/hooks/session-start.ts
customizations/tools/foo.ts                 →  overrides  →  system/tools/foo.ts

Resolution order: Customization → System default

This lets you tweak the reasoning framework, add hooks, or replace tools without modifying system/. Your customizations survive upgrades.

shaka init                    # Set up Shaka (creates dirs, symlinks, installs hooks)
shaka init --claude           # Set up for Claude Code only
shaka init --opencode         # Set up for opencode only
shaka init --all              # Set up for both providers
shaka update                  # Upgrade to latest release (tag-based)
shaka uninstall               # Remove hooks and config
shaka reload-hooks            # Re-discover hooks and regenerate provider configs
shaka doctor                  # Check installation health
shaka mcp serve               # Start MCP server (for Claude Code tool integration)
shaka memory search <query>   # Search session summaries

shaka init does the following:

1. Detects which providers (Claude Code, opencode) are installed
2. Prompts for provider selection (or use --claude/--opencode/--all)
3. Creates user/, memory/, customizations/ directories
4. Symlinks system/ to the repo's defaults/system/
5. Copies user file templates (identity.md, preferences.md, etc.)
6. Registers the shaka package globally via bun link
7. Installs hooks for selected providers
8. Tracks version in .shaka-version

shaka update uses git tags for releases:

1. Fetches latest tags from remote
2. Compares current vs latest version
3. Warns and prompts on major version bumps
4. Checks out the new tag and re-runs init

Shaka uses a structured reasoning framework inspired by PAI's Algorithm, loaded at session start. The AI works through 7 phases — OBSERVE, THINK, PLAN, BUILD, EXECUTE, VERIFY, LEARN — and defines testable success criteria (ISC) before acting. This prevents the common failure of solving one problem while creating another.

To customize, copy system/base-reasoning-framework.md to customizations/ and edit. For details, see Reasoning Framework.

Shaka uses a progressive abstraction model where each layer builds on the previous:

┌─────────────────────────────────────────────────────────────────────────┐
│  SKILLS      │ Multi-step workflows, domain expertise                   │
│              │ Folder with SKILL.md + commands + context                │
│              │ e.g., code-review/, deployment/                          │
├──────────────┼──────────────────────────────────────────────────────────┤
│  COMMANDS    │ Single-purpose prompt + tool invocation        (planned) │
│              │ Slash-invoked, atomic operations                         │
│              │ e.g., /commit, /diff, /lint                              │
├──────────────┼──────────────────────────────────────────────────────────┤
│  TOOLS       │ Deterministic TypeScript functions                       │
│              │ Pure code, no LLM involvement                            │
│              │ e.g., inference.ts                                        │
└──────────────┴──────────────────────────────────────────────────────────┘

Deterministic TypeScript functions that execute code, not prompts. Tools do the heavy lifting before the LLM is involved.

Currently, two tools ship with Shaka:

• inference.ts — Provider-agnostic AI inference (wraps Claude CLI or opencode CLI)
• memory-search.ts — Search session summaries by keyword (exposed via MCP)

Shaka adopts opencode's tool format for consistency across providers. Tools are TypeScript files using the tool() helper:

// Example: ~/.config/shaka/system/tools/my-tool.ts
import { tool } from "@opencode-ai/plugin";

export default tool({
  description: "Describe what the tool does",
  args: {},
  async execute(args, context) {
    // Deterministic code — no LLM involvement
    return "result";
  },
});

Tools are exposed to AI providers via:

• opencode: Symlinked to .opencode/tools/ (native)
• Claude Code: Exposed via shaka mcp serve (MCP server)

Atomic, slash-invoked operations. A command does one thing: invoke tools, add a prompt, and let the model respond. Markdown with YAML frontmatter.

---
name: commit
description: Create a git commit with AI-generated message
---

Check what changed in the working tree, then generate a conventional commit message.

Commands will be the primary user interface. Type /commit and it runs.

Domain containers for complex workflows. A skill is a folder with a SKILL.md and optional supporting files. Skills are markdown-based — they provide context and workflow guidance to the AI, not executable code.

Shipped skills:

skills/code-review/
├── SKILL.md              # Workflow definition and domain knowledge
└── security-rules.md     # Optional supporting context

Skills are invoked by context ("review this PR") or explicitly ("use the code-review skill").

Specialized personas defined as markdown prompt templates. Each agent has a defined role, tool access restrictions, and behavioral guidelines.

12 agents ship with Shaka: Algorithm, Architect, Artist, ClaudeResearcher, CodexResearcher, Designer, Engineer, GeminiResearcher, GrokResearcher, Intern, Pentester, QATester.

---
name: reviewer
description: Code review specialist (read-only)
tools:
  read: true
  write: false
  bash: false
---

You are a code reviewer. You analyze but never modify code.

Event-driven automation. TypeScript scripts that run on specific events.

Shipped hooks:

Supported events:

Planned events:

Persistent context that survives sessions. The memory system captures what happened in each session so the AI can reference past work.

• Session summarization — The session-end hook parses transcripts (Claude Code JSONL or opencode JSON) and generates structured summaries using AI inference
• Summary storage — Summaries are stored as markdown in memory/summaries/ with a JSON index for fast lookup
• Session context — The session-start hook loads recent summaries into context so the AI knows what you worked on recently
• Search — shaka memory search <query> searches summaries by keyword; also available as an MCP tool for in-session search
• Security event logging — The security validator writes logs to memory/security/

Planned: Semantic retrieval via vector search (likely sqlite-vec), tiered memory with importance scoring.

Shaka integrates with two AI coding assistants:

You write hooks once — provider-specific adapters handle the translation. For details on hook abstraction, event mapping, and tool integration, see Providers.

The security validator hook (security-validator.ts) runs on every tool use, checking:

• Bash commands against patterns defined in system/security/patterns.yaml
• File paths for read/write operations (blocks access to sensitive directories)
• Catastrophic operations are blocked outright (e.g., rm -rf /)
• Dangerous operations trigger confirmation prompts

Security events are logged to memory/security/.

# system/security/patterns.yaml
catastrophic:
  - pattern: "rm -rf /"
    description: "Recursive delete from root"
dangerous:
  - pattern: "git push --force"
    description: "Force push (rewrites history)"

Planned: Config-driven allow/deny directory lists, per-agent capability grants.

These are ideas for future development, not yet implemented:

• Interactive TUI — shaka as a standalone terminal interface
• Session management — Persistent sessions across CLI invocations (shaka start, shaka resume, shaka sessions)
• Slash commands — /commit, /diff, /lint style atomic operations
• Single-shot CLI — shaka run "summarize this file", shaka skill list, shaka tool run
• Feature polyfills — Subagent events and background subagents for opencode

Requires Bun and just.

bun install          # Install dependencies
just check           # Run all checks (typecheck + lint + tests)
just test            # Run tests
just typecheck       # Run typechecker
just lint            # Run linter
just format          # Format code

just e2e             # Run all e2e tests
just e2e-claude      # Claude Code e2e only
just e2e-opencode    # opencode e2e only

This project learns from:

• PAI — Hook system, skill patterns, memory architecture
• PAI-OpenCode — PAI port to opencode, hooks→plugins conversion
• Ren — Deterministic-first philosophy, clean directory structure
• openclaw — Gateway pattern, typed workflows, multi-channel approach
• opencode — Provider abstraction, plugin architecture
• Claude Code — Hook system, context injection, subprocess model

MIT