docs: clarified OAuth more

Release v0.4.0: Graph-based agents, remote asset installation, self-update and god-config refactor

.actrc

@@ -0,0 +1,4 @@
+--artifact-server-path=./.act/artifacts
+--cache-server-path=./.act/cache
+--container-options --privileged
+--env ACT=true

.cz.toml

@@ -0,0 +1,10 @@
+[tool.commitizen]
+name = "cz_conventional_commits"
+tag_format = "v$version"
+version_scheme = "semver"
+version_provider = "cargo"
+update_changelog_on_bump = true
+major_version_zero = true
+
+[tool.commitizen.hooks]
+pre-commit = "git add Cargo.toml Cargo.lock"

.github/FUNDING.yml

@@ -0,0 +1 @@
+github: Dark-Alex-17

.github/ISSUE_TEMPLATE/blank_issue.md

@@ -0,0 +1,4 @@
+---
+name: Blank Issue
+about: Create a blank issue.
+---

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -0,0 +1,69 @@
+name: Bug Report
+description: Create a report to help us improve
+labels: bug
+body:
+  - type: markdown
+    attributes:
+      value: Thank you for filing a bug report!
+  - type: textarea
+    id: problem
+    attributes:
+      label: Summary
+      description: >
+        Please provide a short summary of the bug, along with any information
+        you feel relevant to replicate the bug.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction-steps
+    attributes:
+      label: Reproduction Steps
+      value: |
+        I tried this:
+
+        1. `loki`
+
+        I expected this to happen:
+
+        Instead, this happened:
+  - type: textarea
+    id: loki-log
+    attributes:
+      label: Loki log
+      description: Include the Loki log file to help diagnose the issue. (`loki --info` to see the log_path)
+      value: |
+        | OS      | Log file location                                     |
+        | ------- | ----------------------------------------------------- |
+        | Linux   | `~/.cache/loki/loki.log`                      |
+        | Mac     | `~/Library/Logs/loki/loki.log`                |
+        | Windows | `C:\Users\<User>\AppData\Local\loki\loki.log` |
+
+        ```
+        please provide a copy of your loki log file here if possible; you may need to redact some of the lines
+        ```
+
+  - type: input
+    id: platform
+    attributes:
+      label: Platform
+      placeholder: Linux / macOS / Windows
+    validations:
+      required: true
+  - type: input
+    id: terminal-emulator
+    attributes:
+      label: Terminal Emulator
+      placeholder: wezterm 20220101-133340-7edc5b5a
+    validations:
+      required: true
+  - type: input
+    id: loki-version
+    attributes:
+      label: Loki Version
+      description: >
+        Loki version (`loki --version` if using a release, `git describe` if building
+        from main).
+        **Make sure that you are using the [latest loki release](https://github.com/Dark-Alex-17/loki/releases) or a newer main build**
+      placeholder: "loki 0.1.0"
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/enhancement.md

@@ -0,0 +1,13 @@
+---
+name: Enhancement
+about: Suggest an improvement
+title: ''
+labels: enhancement
+assignees: ''
+---
+
+<!--
+Your enhancement may already be reported!
+Please search on the issue tracker before creating a new issue.
+If this is an idea for a feature, please open an "Idea" Discussion instead.
+-->

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,11 @@
+### AI assistance (if any):
+- List tools here and files touched by them
+
+### Authorship & Understanding
+
+- [ ] I wrote or heavily modified this code myself
+- [ ] I understand how it works end-to-end
+- [ ] I can maintain this code in the future
+- [ ] No undisclosed AI-generated code was used
+- [ ] If AI assistance was used, it is documented below
+

.github/workflows/ci.yaml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+    - '*'
+  push:
+    branches:
+    - main
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  all:
+    name: All
+
+    strategy:
+      matrix:
+        os:
+        - ubuntu-latest
+        - macos-latest
+        - windows-latest
+
+    runs-on: ${{matrix.os}}
+
+    env:
+      RUSTFLAGS: --deny warnings
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install Rust Toolchain Components
+      uses: dtolnay/rust-toolchain@stable
+
+    - uses: Swatinem/rust-cache@v2
+
+    - name: Test
+      run: cargo test --all
+
+    - name: Clippy
+      run: cargo clippy --all --all-targets -- -D warnings
+
+    - name: Format
+      run: cargo fmt --all --check

.github/workflows/release.yaml

@@ -0,0 +1,458 @@
+name: Create release
+
+permissions:
+  pull-requests: write
+  contents: write
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump_type:
+        description: "Specify the type of version bump"
+        required: true
+        default: "patch"
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+jobs:
+  bump-version:
+    name: bump-version
+    runs-on: ubuntu-latest
+    steps:
+      - name: Configure SSH for Git
+        if: env.ACT != 'true'
+        run: |
+          mkdir -p ~/.ssh
+          echo "${{ secrets.RELEASE_BOT_SSH_KEY }}" > ~/.ssh/id_ed25519
+          chmod 600 ~/.ssh/id_ed25519
+          ssh-keyscan -H github.com >> ~/.ssh/known_hosts
+
+      - name: Checkout repository
+        if: env.ACT != 'true'
+        uses: actions/checkout@v3
+        with:
+          ssh-key: ${{ secrets.RELEASE_BOT_SSH_KEY }}
+          fetch-depth: 0
+
+      - name: Checkout repository
+        if: env.ACT == 'true'
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install Commitizen
+        run: |
+          python -m pip install --upgrade pip
+          pip install commitizen
+          npm install -g conventional-changelog-cli
+
+      - name: Configure Git user
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version with Commitizen
+        run: |
+          cz bump --yes --increment ${{ github.event.inputs.bump_type }}
+
+      - name: Amend commit message to include '[skip ci]'
+        run: |
+          git commit --amend --no-edit -m "$(git log -1 --pretty=%B) [skip ci]"
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Get the new version tag
+        id: version
+        run: |
+          mkdir -p artifacts
+          NEW_TAG=$(cz version --project)
+          echo "New version: $NEW_TAG"
+          echo "version=$NEW_TAG" >> $GITHUB_ENV
+          echo "$NEW_TAG" > artifacts/release-version
+
+      - name: Get the previous version tag
+        id: prev_version
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 ${GITHUB_SHA}^)
+          echo "Previous tag: $PREV_TAG"
+          echo "prev_version=$PREV_TAG" >> $GITHUB_ENV
+
+      - name: Bump Cargo.toml version
+        shell: bash
+        working-directory: ${{ github.workspace }}
+        env:
+          VERSION: ${{ env.version }}
+        run: |
+          set -euo pipefail
+          : "${VERSION:?env.version is empty}"
+
+          # Ignore Act's local artifact dir noise
+          echo artifacts/ >> .git/info/exclude || true
+
+          # Edit the version line right after name="loki"
+          sed -E -i '
+            /^[[:space:]]*name[[:space:]]*=[[:space:]]*"loki"[[:space:]]*$/ {
+              n
+              s|^[[:space:]]*version[[:space:]]*=[[:space:]]*"[^"]*"|version = "'"$VERSION"'"|
+            }
+          ' Cargo.toml
+
+          cargo update || true
+
+          # Git config that helps in Act
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+          git status --porcelain
+          git diff --name-only -- Cargo.toml Cargo.lock || true
+
+          if ! git diff --quiet -- Cargo.toml Cargo.lock; then
+            git add -u -- Cargo.toml Cargo.lock
+            git commit -m "chore: bump Cargo.toml to $VERSION"
+          else
+            echo "No changes to commit (already at $VERSION)"
+          fi
+
+      - name: Generate changelog for the version bump
+        id: changelog
+        run: |
+          conventional-changelog -p conventionalcommits -i CHANGELOG.md --from ${{ env.prev_version }} --to v${{ env.version }} > artifacts/changelog.md
+
+      - name: Push changes
+        if: env.ACT != 'true'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git push origin --follow-tags
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Upload the changed Cargo files (Act)
+        if: env.ACT == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: bumped-cargo-files
+          path: |
+            Cargo.toml
+            Cargo.lock
+
+  publish-github-release:
+    name: build-release
+    needs: [bump-version]
+    runs-on: ${{ matrix.os }}
+    env:
+      RUST_BACKTRACE: 1
+      BUILD_CMD: cargo
+    strategy:
+      fail-fast: true
+      matrix:
+        include:
+          - target: aarch64-unknown-linux-musl
+            os: ubuntu-latest
+            use-cross: true
+            cargo-flags: ""
+          - target: aarch64-apple-darwin
+            os: macos-latest
+            use-cross: true
+            cargo-flags: ""
+          - target: aarch64-pc-windows-msvc
+            os: windows-latest
+            use-cross: true
+            cargo-flags: ""
+          - target: x86_64-apple-darwin
+            os: macos-latest
+            cargo-flags: ""
+          - target: x86_64-pc-windows-msvc
+            os: windows-latest
+            cargo-flags: ""
+          - target: x86_64-unknown-linux-musl
+            os: ubuntu-latest
+            use-cross: true
+            cargo-flags: ""
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+            cargo-flags: ""
+
+    steps:
+      - name: Check if actor is repository owner
+        if: ${{ github.actor != github.repository_owner && env.ACT != 'true' }}
+        run: |
+          echo "You are not authorized to run this workflow."
+          exit 1
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Ensure repository is up-to-date
+        if: env.ACT != 'true'
+        run: |
+          git fetch --all
+          git pull
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Ensure repository is up-to-date
+        if: env.ACT != 'true'
+        run: |
+          git fetch --all
+          git pull
+
+      - name: Set environment variables
+        shell: bash
+        run: |
+          release_version="$(cat ./artifacts/release-version)"
+          echo "RELEASE_VERSION=$release_version" >> $GITHUB_ENV
+
+      - name: Validate release environment variables
+        run: |
+          echo "Release version: ${{ env.RELEASE_VERSION }}"
+          echo "Changelog body: $(cat artifacts/changelog.md)"
+
+      - name: Get bumped Cargo files (Act)
+        if: env.ACT == 'true'
+        uses: actions/download-artifact@v4
+        with:
+          name: bumped-cargo-files
+          path: ${{ github.workspace }}
+
+      - uses: dtolnay/rust-toolchain@stable
+        name: Set Rust toolchain
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Install cross
+        if: matrix.use-cross
+        uses: taiki-e/install-action@v2
+        with:
+          tool: cross
+
+      - name: Overwrite build command env variable
+        if: matrix.use-cross
+        shell: bash
+        run: echo "BUILD_CMD=cross" >> $GITHUB_ENV
+
+      - name: Install latest LLVM/Clang
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          wget https://apt.llvm.org/llvm.sh
+          chmod +x llvm.sh
+          # omit the version to get the latest stable for your Ubuntu (24.04 "noble" on ubuntu-latest)
+          sudo ./llvm.sh all
+          # ensure libclang dev package is present (adjust the "22" if a newer major exists)
+          sudo apt-get update
+          sudo apt-get install -y libclang-20-dev libclang-dev
+
+      - name: Show Version Information (Rust, cargo, GCC)
+        shell: bash
+        run: |
+          gcc --version || true
+          rustup -V
+          rustup toolchain list
+          rustup default
+          cargo -V
+          rustc -V
+
+      - name: Build
+        shell: bash
+        run: $BUILD_CMD build --locked --release --target=${{ matrix.target }} ${{ matrix.cargo-flags }}
+
+      - name: Verify file
+        shell: bash
+        run: |
+          file target/${{ matrix.target }}/release/loki
+
+      - name: Test
+        if: matrix.target != 'aarch64-apple-darwin' && matrix.target != 'aarch64-pc-windows-msvc'
+        shell: bash
+        run: |
+          set -euxo pipefail
+          if [[ "${{ matrix.use-cross || 'false' }}" == 'true' ]]; then
+            cross test --release --locked --target=${{ matrix.target }} --verbose
+          else
+            cargo test  --release --locked --target=${{ matrix.target }} --verbose
+          fi
+
+      - name: Build Archive
+        shell: bash
+        id: package
+        env:
+          target: ${{ matrix.target }}
+        run: |
+          set -euxo pipefail
+
+          bin=${GITHUB_REPOSITORY##*/}
+          dist_dir=`pwd`/dist
+          name=$bin-$target
+          executable=target/$target/release/$bin
+
+          if [[ "$RUNNER_OS" == "Windows" ]]; then
+            executable=$executable.exe
+          fi
+
+          mkdir $dist_dir
+          cp $executable $dist_dir
+          cd $dist_dir
+
+          if [[ "$RUNNER_OS" == "Windows" ]]; then
+            archive=$dist_dir/$name.zip
+            sha=$dist_dir/$name.sha256
+            7z a $archive *
+            certutil -hashfile $archive sha256 | grep -E [A-Fa-f0-9]{64} > $sha
+            echo "archive=dist/$name.zip" >> $GITHUB_OUTPUT
+            echo "sha=dist/$name.sha256" >> $GITHUB_OUTPUT
+          else
+            archive=$dist_dir/$name.tar.gz
+            sha=$dist_dir/$name.sha256
+            tar -czf $archive *
+            shasum -a 256 $archive > $sha
+            echo "archive=dist/$name.tar.gz" >> $GITHUB_OUTPUT
+            echo "sha=dist/$name.sha256" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Publish Archive and SHA
+        if: env.ACT != 'true'
+        uses: softprops/action-gh-release@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          files: |
+            ${{ steps.package.outputs.archive }} 
+            ${{ steps.package.outputs.sha }}
+          tag_name: v${{ env.RELEASE_VERSION }}
+          name: "v${{ env.RELEASE_VERSION }}"
+          body_path: artifacts/changelog.md
+          prerelease: false
+
+      - name: Add artifacts
+        shell: bash
+        run: |
+          [[ -d artifacts ]] || mkdir -p artifacts
+          cp ${{ steps.package.outputs.archive }} artifacts/
+          cp ${{ steps.package.outputs.sha }} artifacts/
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: artifacts-v${{ env.RELEASE_VERSION }}-${{ matrix.target }}
+          path: artifacts
+          overwrite: true
+
+  publish-homebrew-formula:
+    needs: [publish-github-release]
+    name: Update Homebrew formulas
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check if actor is repository owner
+        if: ${{ github.actor != github.repository_owner  && env.ACT != 'true' }}
+        run: |
+          echo "You are not authorized to run this workflow."
+          exit 1
+
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Get release artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Set release assets and version
+        shell: bash
+        run: |
+          # Set environment variables
+          macos_sha="$(cat ./artifacts/loki-x86_64-apple-darwin.sha256 | awk '{print $1}')"
+          echo "MACOS_SHA=$macos_sha" >> $GITHUB_ENV
+          macos_sha_arm="$(cat ./artifacts/loki-aarch64-apple-darwin.sha256 | awk '{print $1}')"
+          echo "MACOS_SHA_ARM=$macos_sha_arm" >> $GITHUB_ENV
+          linux_sha="$(cat ./artifacts/loki-x86_64-unknown-linux-musl.sha256 | awk '{print $1}')"
+          echo "LINUX_SHA=$linux_sha" >> $GITHUB_ENV
+          release_version="$(cat ./artifacts/release-version)"
+          echo "RELEASE_VERSION=$release_version" >> $GITHUB_ENV
+
+      - name: Validate release environment variables
+        run: |
+          echo "Release SHA macos: ${{ env.MACOS_SHA }}"
+          echo "Release SHA macos-arm: ${{ env.MACOS_SHA_ARM }}"
+          echo "Release SHA linux musl: ${{ env.LINUX_SHA }}"
+          echo "Release version: ${{ env.RELEASE_VERSION }}"
+
+      - name: Execute Homebrew packaging script
+        if: env.ACT != 'true'
+        run: |
+          # run packaging script
+          python "./deployment/homebrew/packager.py" ${{ env.RELEASE_VERSION }} "./deployment/homebrew/loki.rb.template" "./loki.rb" ${{ env.MACOS_SHA }} ${{ env.MACOS_SHA_ARM }} ${{ env.LINUX_SHA }}
+
+      - name: Push changes to Homebrew tap
+        if: env.ACT != 'true'
+        env:
+          TOKEN: ${{ secrets.LOKI_GITHUB_TOKEN }}
+        run: |
+          # push to Git
+          git config --global user.name "Dark-Alex-17"
+          git config --global user.email "alex.j.tusa@gmail.com"
+          git clone https://Dark-Alex-17:${{ secrets.LOKI_GITHUB_TOKEN }}@github.com/Dark-Alex-17/homebrew-loki.git
+          rm homebrew-loki/Formula/loki.rb
+          cp loki.rb homebrew-loki/Formula
+          cd homebrew-loki
+          git add .
+          git diff-index --quiet HEAD || git commit -am "Update formula for Loki release ${{ env.RELEASE_VERSION }}"
+          git push https://$TOKEN@github.com/Dark-Alex-17/homebrew-loki.git
+
+  publish-crate:
+    needs: publish-github-release
+    name: Publish Crate
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check if actor is repository owner
+        if: ${{ github.actor != github.repository_owner  && env.ACT != 'true' }}
+        run: |
+          echo "You are not authorized to run this workflow."
+          exit 1
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Get bumped Cargo files (Act)
+        if: env.ACT == 'true'
+        uses: actions/download-artifact@v4
+        with:
+          name: bumped-cargo-files
+          path: ${{ github.workspace }}
+
+      - name: Ensure repository is up-to-date
+        if: env.ACT != 'true'
+        run: |
+          git fetch --all
+          git pull
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - uses: katyo/publish-crates@v2
+        if: env.ACT != 'true'
+        with:
+          registry-token: ${{ secrets.CARGO_REGISTRY_TOKEN }}

.gitignore

@@ -0,0 +1,7 @@
+/target
+/tmp
+/.env
+!cli/**
+.idea/
+/loki.iml
+/.idea/

.loki-project.json

@@ -0,0 +1 @@
+{"type":"rust","build":"cargo build","test":"cargo test","check":"cargo check","_detected_by":"heuristic","_cached_at":"2026-04-13T13:36:33-06:00"}

.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+repos:
+- hooks:
+  - id: commitizen
+  - id: commitizen-branch
+    stages:
+    - pre-push
+  repo: https://github.com/commitizen-tools/commitizen
+  rev: v3.30.0

CHANGELOG.md

@@ -0,0 +1,269 @@
+## v0.4.0 (2026-05-23)
+
+### Feat
+
+- LLM node failures propgate up
+- Added .install remote tab completions to the REPL
+- feature complete install remote with category selection
+- Support to interactively add secrets to Loki that are missing from MCP configs when merging
+- Added MCP config merging support for remote asset installations
+- install remote now writes files to disk
+- Created basic install_remote functions
+- Created a more comprehensive and immediately useful default config for first runs
+- Created an example graph-based agent called deep-research
+- Improved coder agent that is now a graph-based agent
+- Removed indicatif spinners. The UX just won't stop clobbering for parallel graph nodes
+- Added agent variables support for graph agents and improved script executor to use the same environment variables as normal agent tool calling for further flexibility
+- Improved UX with colored spinners for parallel graph agents and no clobbering outputs for sub-agents
+- created new graph-based deep-research agent
+- improved UX for parallel graph execution
+- added branch progress tracker for better visualization of parallel graph super-steps
+- Removed the jira-helper agent and replaced it with the atlassian role
+- created the RenderMode enum to suppress stdout streaming during parallel graph super-steps
+- Full support for map node types
+- implemented the frontier-based scheduling for the graph executor with simplified state management (gotta love .clone)
+- validation support for parallel graph execution; restricted map nodes to only run for nodes without next targets and not supporting chained map nodes
+- created the staging area for state merges per super-step and created the built-in reducers (and their application) for the state merge phase of a super step
+- scaffolding work for fan-out nodes for parallel branch execution support and stubbed out Map node types
+- Loki can now update itself via .update and --update commands
+- added a .edit command for editing the MCP configuration file
+- Created a new .install command to install bundled assets on-demand
+- migrated llm node validation to graph loading time instead of graph runtime
+- ripped out user input timeout scaffolding for approval and input node types; implementation can't be done cleanly
+- added additional support for all RAG-configuration fields in RAG nodes
+- initial support for RAG nodes in the graph execution system
+- implemented structured logging for graph execution
+- merged normal agent config and graph agent configs into one file (either/or)
+- added structured-output extraction for llm and agent nodes
+- created full llm node runtime implementation
+- scaffolded together the initial llm node type and its executor
+- wired together graph execution and agent graph dispatch
+- implemented support for the graph executor
+- created the approval node executor and the input node executor for user interaction
+- Added initial support for native Loki agent nodes in the graph-based agent system
+- Added direct script invocation support for graph-based agents
+- Added graph validation
+- Implemented state management for agent graphs
+- initial agent graph scaffolding
+- add auto-continue support to all contexts
+- dynamic tab completions now show the sessions for a given agent instead of only listing global sessions
+- legacy SSE support for MCP server configurations
+- support http/sse transport types for MCP server configurations so it fully supports claude desktop-style MCP configs
+- 99% complete migration to new state structs to get away from God-Config struct; i.e. AppConfig, AppState, and RequestContext
+- Automatic runtime customization using shebangs
+- Created a demo TypeScript tool and a get_current_weather function in TypeScript
+- Updated the Python demo tool to show all possible parameter types and variations
+- Added TypeScript tool support using the refactored common ScriptedLanguage trait
+
+### Fix
+
+- Generified the functions usage of script detection for an executable bit on unix systems
+- merge required claude code system prompt into instructions
+- updated argc argument passing in run-tool and run-agent scripts
+- Added additional graph validation for parallel reads and writes with dependencies between nodes states
+- bug in next_single method and improved outcome handling for LLM node execution
+- inline RAG bug when globbing files by extension without subdirectory globbing
+- update the estimate_token_length function to use the standard word count method
+- removed unnecessary regenerate logic for sessions and use the same logic for all contexts; prevents a panic on empty message list
+- error when users try to start a session on a graph agent
+- added on_other field for approval nodes so users can specify an alternative free-text target when none of the options match what they want
+- accidentally added back in full agent tools on LLM nodes
+- Improve the coder agent's usage of tools
+- make the agent__collect escalation-aware so it doesn't freeze on sub-agent escalations
+- check for an existing session before starting up MCP servers when switching to a role
+- do not switch to agent if a session is active.
+- Do not append todo instructions when function calling is disabled
+- a bug in the dynamic completions because the crate name is loki-ai but the binary is named loki
+- bug found by copilot that would create a lock on the PollSender for sse-based MCP servers
+- Accidental shadow of temp_file function for Windows function calling
+- upgraded to newer rmcp version to get native-tls support
+- RagCache was not being used for agent and sub-agent instantiation
+- TypeScript function args were being passed as objects rather than direct parameters
+- Added in forgotten wrapper scripts for TypeScript tools
+- don't shadow variables in binary path handling for Windows
+- Tool call improvements for Windows systems
+
+### Refactor
+
+- migrated llm nodes to use Roles to simplify instructions handling and to function like inline roles
+- migrated the next_node and apply_state_updates logic for LLM nodes into the LlmExecutor
+- fully complete state re-architecting
+- Fully ripped out the god Config struct
+- Deprecated old Config struct initialization logic
+- migrate functions and MCP servers to AppConfig
+- Migrate the vault/bare_init logic
+- created a single install_builtins free function to remove from Config::init
+- partial migration to init in AppConfig
+- Extracted common Python parser logic into a common.rs module
+- python tools now use tree-sitter queries instead of AST
+
+## v0.3.0 (2026-04-02)
+
+### Feat
+
+- Added `todo__clear` function to the todo system and updated REPL commands to have a .clear todo as well for significant changes in agent direction
+- Added available tools to prompts for sisyphus and code-reviewer agent families
+- Added available tools to coder prompt
+- Improved token efficiency when delegating from sisyphus -> coder
+- modified sisyphus agents to use the new ddg-search MCP server for web searches instead of built-in model searches
+- Added support for specifying a custom response to multiple-choice prompts when nothing suits the user's needs
+- Supported theming in the inquire prompts in the REPL
+- Added the duckduckgo-search MCP server for searching the web (in addition to the built-in tools for web searches)
+- Support for Gemini OAuth
+- Support authenticating or refreshing OAuth for supported clients from within the REPL
+- Allow first-runs to select OAuth for supported providers
+- Support OAuth authentication flows for Claude
+- Improved MCP server spinup and spindown when switching contexts or settings in the REPL: Modify existing config rather than stopping all servers always and re-initializing if unnecessary
+- Allow the explore agent to run search queries for understanding docs or API specs
+- Allow the oracle to perform web searches for deeper research
+- Added web search support to the main sisyphus agent to answer user queries
+- Created a CodeRabbit-style code-reviewer agent
+- Added configuration option in agents to indicate the timeout for user input before proceeding (defaults to 5 minutes)
+- Added support for sub-agents to escalate user interaction requests from any depth to the parent agents for user interactions
+- built-in user interaction tools to remove the need for the list/confirm/etc prompts in prompt tools and to enhance user interactions in Loki
+- Experimental update to sisyphus to use the new parallel agent spawning system
+- Added an agent configuration property that allows auto-injecting sub-agent spawning instructions (when using the built-in sub-agent spawning system)
+- Auto-dispatch support of sub-agents and support for the teammate pattern between subagents
+- Full passive task queue integration for parallelization of subagents
+- Implemented initial scaffolding for built-in sub-agent spawning tool call operations
+- Initial models for agent parallelization
+- Added interactive prompting between the LLM and the user in Sisyphus using the built-in Bash utils scripts
+
+### Fix
+
+- Clarified user text input interaction
+- recursion bug with similarly named Bash search functions in the explore agent
+- updated the error for unauthenticated oauth to include the REPL .authenticated command
+- Corrected a bug in the coder agent that wasn't outputting a summary of the changes made, so the parent Sisyphus agent has no idea if the agent worked or not
+- Claude code system prompt injected into claude requests to make them valid once again
+- Do not inject tools when models don't support them; detect this conflict before API calls happen
+- The REPL .authenticate command works from within sessions, agents, and roles with pre-configured models
+- Implemented the path normalization fix for the oracle and explore agents
+- Updated the atlassian MCP server endpoint to account for future deprecation
+- Fixed a bug in the coder agent that was causing the agent to create absolute paths from the current directory
+- the updated regex for secrets injection broke MCP server secrets interpolation because the regex greedily matched on new lines, replacing too much content. This fix just ignores commented out lines in YAML files by skipping commented out lines.
+- Don't try to inject secrets into commented-out lines in the config
+- Removed top_p parameter from some agents so they can work across model providers
+- Improved sub-agent stdout and stderr output for users to follow
+- Inject agent variables into environment variables for global tool calls when invoked from agents to modify global tool behavior
+- Removed the unnecessary execute_commands tool from the oracle agent
+- Added auto_confirm to the coder agent so sub-agent spawning doesn't freeze
+- Fixed a bug in the new supervisor and todo built-ins that was causing errors with OpenAI models
+- Added condition to sisyphus to always output a summary to clearly indicate completion
+- Updated the sisyphus prompt to explicitly tell it to delegate to the coder agent when it wants to write any code at all except for trivial changes
+- Added back in the auto_confirm variable into sisyphus
+- Removed the now unnecessary is_stale_response that was breaking auto-continuing with parallel agents
+- Bypassed enabled_tools for user interaction tools so if function calling is enabled at all, the LLM has access to the user interaction tools when in REPL mode
+- When parallel agents run, only write to stdout from the parent and only display the parent's throbber
+- Forgot to implement support for failing a task and keep all dependents blocked
+- Clean up orphaned sub-agents when the parent agent
+- Fixed the bash prompt utils so that they correctly show output when being run by a tool invocation
+- Forgot to automatically add the bidirectional communication back up to parent agents from sub-agents (i.e. need to be able to check inbox and send messages)
+- Agent delegation tools were not being passed into the {{__tools__}} placeholder so agents weren't delegating to subagents
+
+### Refactor
+
+- Made the oauth module more generic so it can support loopback OAuth (not just manual)
+- Changed the default session name for Sisyphus to temp (to require users to explicitly name sessions they wish to save)
+- Updated the sisyphus agent to use the built-in user interaction tools instead of custom bash-based tools
+- Cleaned up some left-over implementation stubs
+
+## v0.2.0 (2026-02-14)
+
+### Feat
+
+- Simplified sisyphus prompt to improve functionality
+- Supported the injection of RAG sources into the prompt, not just via the `.sources rag` command in the REPL so models can directly reference the documents that supported their responses
+- Created the Sisyphus agent to make Loki function like Claude Code, Gemini, Codex, etc.
+- Created the Oracle agent to handle high-level architectural decisions and design questions about a given codebase
+- Updated the coder agent to be much more task-focused and to be delegated to by Sisyphus
+- Created the explore agent for exploring codebases to help answer questions
+- Use the official atlassian MCP server for the jira-helper agent
+- Created fs_glob to enable more targeted file exploration utilities
+- Created a new tool 'fs_grep' to search a given file's contents for relevant lines to reduce token usage for smaller models
+- Created the new fs_read tool to enable controlled reading of a file
+- Let agent level variables be defined to bypass guard protections for tool invocations
+- Implemented a built-in task management system to help smaller LLMs complete larger multistep tasks and minimize context drift
+- Improved tool and MCP invocation error handling by returning stderr to the model when it is available
+- Added variable interpolation for conversation starters in agents
+- Implemented retry logic for failed tool invocations so the LLM can learn from the result and try again; Also implemented chain loop detection to prevent loops
+- Added gemini-3-pro to the supported vertexai models
+- Added an environment variable that lets users bypass guard operations in bash scripts. This is useful for agent routing
+- Added support for thought-signatures for Gemini 3+ models
+
+### Fix
+
+- Improved continuation prompt to not make broad todo-items
+- Allow auto-continuation to work in agents after a session is compressed and if there's still unfinish items in the to-do list
+- fs_ls and fs_cat outputs should always redirect to "$LLM_OUTPUT" including on errors.
+- Claude tool calls work incorrectly when tool doesn't require any arguments or flags; would provide an empty JSON object or error on no args
+- Fixed a bug where --agent-variable values were not being passed to the agents
+
+## v0.1.3 (2025-12-13)
+
+### Feat
+
+- Improved MCP implementation to minimize the tokens needed to utilize it so it doesn't quickly overwhelm the token space for a given model
+
+## v0.1.2 (2025-11-08)
+
+### Refactor
+
+- Gave the GitHub MCP server a default placeholder value that doesn't require the vault
+
+## v0.1.1 (2025-11-08)
+
+## v0.1.0 (2025-11-07)
+
+### Refactor
+
+- Updated to the most recent Rust version with 2024 syntax
+
+## v0.0.1 (2025-11-07)
+
+### Feat
+
+- Added the agents directory to sysinfo output
+- Added built-in macros
+- Updated the example role configuration file to also have the prompt field
+- Updated the code role
+- Secret injection as environment variables into agent tools
+- Removed the server functionality
+- Require Vault set up for first-time setup so all passed in secrets can be encrypted right off the bat
+- Added static completions via a --completions flag
+- Support for secret injection into the global config file (API keys, for example)
+- Improved MCP handling toggle handling
+- Secret injection into the MCP configuration
+- added REPL support for interacting with the Loki vault
+- Integrated gman with Loki to create a vault and added flags to configure the Loki vault
+- Added a default session to the jira helper to make interaction more natural
+- Created the repo-analyzer role
+- Created the coder and sql agents
+- Cleaned the built-in functions to not have leftover dependencies
+- Created additional built-in roles for slack, repo analysis, and github
+- Install built-in agents
+- Embedded baseline MCP config and global tools
+
+### Fix
+
+- Corrected a typo for sourcing the bash utility script in some agent definitions
+
+### Refactor
+
+- Changed the name of the summary_prompt setting to summary_context_prompt
+- Renamed summarize_prompt setting to summarization_prompt
+- Renamed the compress_threshold setting to compression_threshold
+- Migrated around the location of some of the more large documents for documentation
+- Factored out the macros structs from the large config module
+- Refactored mcp_servers and function_calling to mcp_server_support and function_calling_support to make the purpose of the fields more clear
+- Refactored the use_mcp_servers field to enabled_mcp_servers to make the purpose of the field more clear
+- Refactored use_tools field to enabled_tools field to make the use of the field more clear
+- Removed the use of the tools.txt file and added tool visibility declarations to the global configuration file
+- Agents that depend on global tools now have all binaries compiled and stored in the agent's bin directory so multiple agents can run at once
+- Removed the git MCP server and used the newer, better mcp-server-docker for local docker integration
+- Renamed the argument for the --completions flag to SHELL
+- Updated the instructions for the jira-helper agent
+- Modified the default PS1 look
+- Fixed a linting issue for Windows builds
+- Changed the name of agent_prelude to agent_session to make its purpose more clear
+- Removed leftover javascript function support; will not implement

CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+alex.j.tusa@gmail.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing
+Contributors are very welcome! **No contribution is too small and all contributions are valued.**
+
+## Rust
+You'll need to have the stable Rust toolchain installed in order to develop Loki.
+
+The Rust toolchain (stable) can be installed via rustup using the following command:
+
+```shell
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+This will install `rustup`, `rustc` and `cargo`. For more information, refer to the [official Rust installation documentation](https://www.rust-lang.org/tools/install).
+
+## Commitizen
+[Commitizen](https://github.com/commitizen-tools/commitizen?tab=readme-ov-file) is a nifty tool that helps us write better commit messages. It ensures that our
+commits have a consistent style and makes it easier to generate CHANGELOGS. Additionally,
+Commitizen is used to run pre-commit checks to enforce style constraints.
+
+To install `commitizen` and the `pre-commit` prerequisite, run the following command:
+
+```shell
+python3 -m pip install commitizen pre-commit
+```
+
+### Commitizen Quick Guide
+To see an example commit to get an idea for the Commitizen style, run:
+
+```shell
+cz example
+```
+
+To see the allowed types of commits and their descriptions, run:
+
+```shell
+cz info
+```
+
+If you'd like to create a commit using Commitizen with an interactive prompt to help you get
+comfortable with the style, use:
+
+```shell
+cz commit
+```
+
+## Setup workspace
+
+1. Clone this repo
+2. Run `cargo test` to set up hooks
+3. Make changes
+4. Run the application using `just run` or `just run`
+   - Install `just` (`cargo install just`) if you haven't already to use the [justfile](./justfile) in this project.
+5. Commit changes. This will trigger pre-commit hooks that will run format, test and lint. If there are errors or 
+   warnings from Clippy, please fix them.
+6. Push your code to a new branch named after the feature/bug/etc. you're adding. This will trigger pre-push hooks that 
+   will run lint and test.
+7. Create a PR
+
+### CI/CD Testing with Act
+If you also are planning on testing out your changes before pushing them with [Act](https://github.com/nektos/act), you will need to set up `act`,
+`docker`, and configure your local system to run different architectures:
+
+1. Install `docker` by following the instructions on the [official Docker installation page](https://docs.docker.com/get-docker/).
+2. Install `act` by following the instructions on the [official Act installation page](https://nektosact.com/installation/index.html).
+3. Install `binfmt` on your system once so that `act` can run the correct architecture for the CI/CD workflows.
+   You can do this by running:
+   ```shell
+   sudo docker run --rm --privileged tonistiigi/binfmt --install all
+   ```
+
+Then, you can run workflows locally without having to commit and see if the GitHub action passes or fails.
+
+**For example**: To test the [release.yml](.github/workflows/release.yaml) workflow locally, you can run:
+
+```shell
+act -W .github/workflows/release.yml --input_type bump=minor
+```
+
+ ## Authorship Policy
+
+All code in this repository is written and reviewed by humans. AI-generated code (e.g., Copilot, ChatGPT,
+Claude, etc.) is not permitted unless explicitly disclosed and approved.
+
+Submissions must certify that the contributor understands and can maintain the code they submit.
+
+## Questions? Reach out to me!
+If you encounter any questions while developing Loki, please don't hesitate to reach out to me at 
+alex.j.tusa@gmail.com. I'm happy to help contributors in any way I can, regardless of if they're new or experienced!

CREDITS.md

@@ -0,0 +1,31 @@
+# Credits
+
+## AIChat
+Loki originally started as a fork of the fantastic
+[AIChat CLI](https://github.com/sigoden/aichat). The initial goal was simply
+to fix a bug in how MCP servers worked with AIChat, allowing different MCP
+servers to be specified per agent. Since then, Loki has evolved far beyond
+its original scope and grown into a passion project with a life of its own.
+
+Today, Loki includes first-class MCP server support (for both local and remote
+servers), a built-in vault for interpolating secrets in configuration files,
+built-in agents and macros, dynamic tab completions, integrated custom
+functions (no external `argc` dependency), improved documentation, and much
+more with many more ideas planned for the future.
+
+Loki is now developed and maintained as an independent project. Full credit
+for the original foundation goes to the developers of the wonderful
+AIChat project.
+
+This project is not affiliated with or endorsed by the AIChat maintainers.
+
+## AIChat
+
+Loki originally began as a fork of [AIChat CLI](https://github.com/sigoden/aichat),
+created and maintained by the AIChat contributors.
+
+While Loki has since diverged significantly and is now developed as an
+independent project, its early foundation and inspiration came from the
+AIChat project.
+
+AIChat is licensed under the MIT License.

Cargo.toml

@@ -0,0 +1,147 @@
+[package]
+name = "loki-ai"
+version = "0.4.0"
+edition = "2024"
+authors = ["Alex Clarke <alex.j.tusa@gmail.com>"]
+description = "An all-in-one, batteries included LLM CLI Tool"
+keywords = ["chatgpt", "llm", "cli", "ai", "repl"]
+homepage = "https://github.com/Dark-Alex-17/loki"
+repository = "https://github.com/Dark-Alex-17/loki"
+categories = ["command-line-utilities"]
+readme = "README.md"
+license = "MIT"
+rust-version = "1.95.0"
+exclude = [".github", "CONTRIBUTING.md"]
+
+[dependencies]
+anyhow = "1.0.69"
+bytes = "1.4.0"
+clap = { version = "4.5.40", features = ["cargo", "derive", "wrap_help"] }
+dirs = "6.0.0"
+dunce = "1.0.5"
+futures-util = "0.3.29"
+inquire = "0.9.4"
+is-terminal = "0.4.9"
+reedline = "0.47.0"
+serde = { version = "1.0.152", features = ["derive"] }
+serde_json = { version = "1.0.93", features = ["preserve_order"] }
+serde_yaml = "0.9.17"
+tokio = { version = "1.34.0", features = [
+  "rt",
+  "time",
+  "macros",
+  "signal",
+  "rt-multi-thread",
+  "full",
+] }
+crossterm = "0.29.0"
+chrono = "0.4.23"
+bincode = { version = "2.0.0", features = [
+  "serde",
+  "std",
+], default-features = false }
+parking_lot = "0.12.1"
+fancy-regex = "0.14.0"
+base64 = "0.22.0"
+nu-ansi-term = "0.50.0"
+async-trait = "0.1.74"
+textwrap = "0.16.0"
+ansi_colours = "1.2.2"
+eventsource-stream = "0.2.3"
+log = "0.4.28"
+log4rs = { version = "1.4.0", features = ["file_appender"] }
+shell-words = "1.1.0"
+sha2 = "0.10.8"
+unicode-width = "0.2.0"
+async-recursion = "1.1.1"
+http = "1.1.0"
+indexmap = { version = "2.2.6", features = ["serde"] }
+hmac = "0.12.1"
+aws-smithy-eventstream = "0.60.4"
+urlencoding = "2.1.3"
+json-patch = { version = "4.0.0", default-features = false }
+bitflags = "2.5.0"
+path-absolutize = "3.1.1"
+hnsw_rs = "0.3.0"
+uuid = { version = "1.9.1", features = ["v4"] }
+scraper = { version = "0.23.1", default-features = false, features = [
+  "deterministic",
+] }
+sys-locale = "0.3.1"
+html_to_markdown = "0.1.0"
+rust-embed = "8.5.0"
+os_info = { version = "3.8.2", default-features = false }
+bm25 = { version = "2.0.1", features = ["parallelism"] }
+which = "8.0.0"
+fuzzy-matcher = "0.3.7"
+terminal-colorsaurus = "0.4.8"
+duct = "1.0.0"
+argc = "1.23.0"
+strum_macros = "0.27.2"
+indoc = "2.0.6"
+rmcp = { version = "1.5.0", features = [
+  "client",
+  "transport-child-process",
+  "transport-streamable-http-client-reqwest",
+  "reqwest-native-tls",
+] }
+num_cpus = "1.17.0"
+tree-sitter = "0.26.8"
+tree-sitter-python = "0.25.0"
+tree-sitter-typescript = "0.23"
+colored = "3.0.0"
+clap_complete = { version = "4.5.58", features = ["unstable-dynamic"] }
+gman = "0.4.1"
+clap_complete_nushell = "4.5.9"
+open = "5"
+rand = { version = "0.10.0", features = ["default"] }
+url = "2.5.8"
+self_update = { version = "0.44", default-features = false, features = [
+  "reqwest",
+  "rustls",
+  "archive-tar",
+  "compression-flate2",
+  "archive-zip",
+  "compression-zip-deflate",
+] }
+
+[dependencies.reqwest]
+version = "0.13.3"
+features = [
+  "json",
+  "multipart",
+  "stream",
+  "form",
+  "socks",
+  "rustls",
+]
+default-features = false
+
+[dependencies.syntect]
+version = "5.0.0"
+default-features = false
+features = ["parsing", "regex-onig", "plist-load"]
+
+[target.'cfg(target_os = "macos")'.dependencies]
+crossterm = { version = "0.29.0", features = ["use-dev-tty"] }
+
+[target.'cfg(target_os = "linux")'.dependencies]
+arboard = { version = "3.3.0", default-features = false, features = [
+  "wayland-data-control",
+] }
+
+[target.'cfg(not(any(target_os = "linux", target_os = "android", target_os = "emscripten")))'.dependencies]
+arboard = { version = "3.3.0", default-features = false }
+
+[dev-dependencies]
+pretty_assertions = "1.4.0"
+serial_test = "3"
+
+[[bin]]
+name = "loki"
+path = "src/main.rs"
+
+[profile.release]
+lto = true
+strip = true
+opt-level = "z"

LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 sigoden
+Copyright (c) 2025 Alexander J. Clarke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,294 @@
-# loki
-An all-in-one, batteries included LLM CLI tool
+# Loki: All-in-one, batteries-included LLM CLI Tool
+
+![Test](https://github.com/Dark-Alex-17/loki/actions/workflows/ci.yaml/badge.svg)
+[![crates.io link](https://img.shields.io/crates/v/loki-ai.svg)](https://crates.io/crates/loki-ai)
+![Release](https://img.shields.io/github/v/release/Dark-Alex-17/loki?color=%23c694ff)
+![Crate.io downloads](https://img.shields.io/crates/d/loki-ai?label=Crate%20downloads)
+[![GitHub Downloads](https://img.shields.io/github/downloads/Dark-Alex-17/loki/total.svg?label=GitHub%20downloads)](https://github.com/Dark-Alex-17/loki/releases)
+
+Loki is an all-in-one, batteries-included, LLM CLI tool featuring Shell Assistant, CLI & REPL Mode, RAG, AI Tools & 
+Agents, and More.
+
+It is designed to include a number of useful agents, roles, macros, and more so users can get up and running with Loki 
+in as little time as possible. You can also install entire bundles of agents, roles, macros, tools, and MCP servers from 
+any git repository. See [Sharing Configurations](https://github.com/Dark-Alex-17/loki/wiki/Sharing-Configurations) for more information.
+
+![Agent example](https://raw.githubusercontent.com/wiki/Dark-Alex-17/loki/images/agents/sql.gif)
+
+Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration guide](https://github.com/Dark-Alex-17/loki/wiki/AIChat-Migration) to get started.
+
+## Quick Links
+* [AIChat Migration Guide](https://github.com/Dark-Alex-17/loki/wiki/AIChat-Migration): Coming from AIChat? Follow the migration guide to get started.
+* [Installation](#install): Install Loki
+* [Getting Started](#getting-started): Get started with Loki by doing first-run setup steps.
+* [Sharing Configurations](https://github.com/Dark-Alex-17/loki/wiki/Sharing-Configurations): Install bundles of agents, roles, macros, tools, and MCP servers from any git repo, and share your own.
+* [REPL](https://github.com/Dark-Alex-17/loki/wiki/REPL): Interactive Read-Eval-Print Loop for conversational interactions with LLMs and Loki.
+  * [Custom REPL Prompt](https://github.com/Dark-Alex-17/loki/wiki/REPL-Prompt): Customize the REPL prompt to provide useful contextual information.
+* [Vault](https://github.com/Dark-Alex-17/loki/wiki/Vault): Securely store and manage sensitive information such as API keys and credentials.
+* [Shell Integrations](https://github.com/Dark-Alex-17/loki/wiki/Shell-Integrations): Seamlessly integrate Loki with your shell environment for enhanced command-line assistance.
+* [Function Calling](https://github.com/Dark-Alex-17/loki/wiki/Tools): Leverage function calling capabilities to extend Loki's functionality with custom tools
+    * [Creating Custom Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Tools): You can create your own custom tools to enhance Loki's capabilities.
+        * [Create Custom Python Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Tools#custom-python-based-tools)
+        * [Create Custom TypeScript Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Tools#custom-typescript-based-tools)
+        * [Create Custom Bash Tools](https://github.com/Dark-Alex-17/loki/wiki/Custom-Bash-Tools)
+            * [Bash Prompt Utilities](https://github.com/Dark-Alex-17/loki/wiki/Bash-Prompt-Helpers)
+* [First-Class MCP Server Support](https://github.com/Dark-Alex-17/loki/wiki/MCP-Servers): Easily connect and interact with MCP servers for advanced functionality.
+* [Macros](https://github.com/Dark-Alex-17/loki/wiki/Macros): Automate repetitive tasks and workflows with Loki "scripts" (macros).
+* [RAG](https://github.com/Dark-Alex-17/loki/wiki/RAG): Retrieval-Augmented Generation for enhanced information retrieval and generation.
+* [Sessions](https://github.com/Dark-Alex-17/loki/wiki/Sessions): Manage and persist conversational contexts and settings across multiple interactions.
+* [Roles](https://github.com/Dark-Alex-17/loki/wiki/Roles): Customize model behavior for specific tasks or domains.
+* [Agents](https://github.com/Dark-Alex-17/loki/wiki/Agents): Leverage AI agents to perform complex tasks and workflows, including sub-agent spawning, teammate messaging, and user interaction tools.
+    * [Graph Agents](https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents): Define an agent as a declarative, YAML-driven workflow. A directed graph of typed nodes (LLM calls, scripts, approvals, user input, RAG retrieval, sub-agent spawns).
+* [Todo System](https://github.com/Dark-Alex-17/loki/wiki/TODO-System): Built-in task tracking for improved LLM reliability with smaller models.
+* [Environment Variables](https://github.com/Dark-Alex-17/loki/wiki/Environment-Variables): Override and customize your Loki configuration at runtime with environment variables.
+* [Client Configurations](https://github.com/Dark-Alex-17/loki/wiki/Clients): Configuration instructions for various LLM providers.
+    * [Authentication (API Key & OAuth)](https://github.com/Dark-Alex-17/loki/wiki/Clients#authentication): Authenticate with API keys or OAuth for subscription-based access.
+    * [Patching API Requests](https://github.com/Dark-Alex-17/loki/wiki/Patches): Learn how to patch API requests for advanced customization.
+* [Custom Themes](https://github.com/Dark-Alex-17/loki/wiki/Themes): Change the look and feel of Loki to your preferences with custom themes.
+* [History](#history): A history of how Loki came to be.
+
+## Prerequisites
+Loki requires the following tools to be installed on your system:
+* [jq](https://github.com/jqlang/jq)
+    * `brew install jq`
+* [usql](https://github.com/xo/usql) (For the `sql` agent)
+    * `brew install xo/xo/usql`
+* [docker](https://docs.docker.com/engine/install/)
+* [uv](https://docs.astral.sh/uv/getting-started/installation/)
+    * `curl -LsSf https://astral.sh/uv/install.sh | sh`
+
+These tools are used to provide various functionalities within Loki, such as document processing, JSON manipulation,
+etc., and they are used within agents and tools.
+
+## Install
+
+### Cargo
+If you have Cargo installed, then you can install `loki` from Crates.io:
+
+```shell
+cargo install loki-ai # Binary name is `loki`
+
+# If you encounter issues installing, try installing with '--locked'
+cargo install --locked loki-ai
+```
+
+### Homebrew (Mac/Linux)
+To install Loki from Homebrew, install the `loki` tap. Then you'll be able to install `loki`:
+
+```shell
+brew tap Dark-Alex-17/loki
+brew install loki
+
+# If you need to be more specific, use:
+brew install Dark-Alex-17/loki/loki
+```
+
+To upgrade `loki` using Homebrew:
+
+```shell
+brew upgrade loki
+```
+
+### Scripts
+#### Linux/MacOS (`bash`)
+You can use the following command to run a bash script that downloads and installs the latest version of `loki` for your
+OS (Linux/MacOS) and architecture (x86_64/arm64):
+
+```shell
+curl -fsSL https://raw.githubusercontent.com/Dark-Alex-17/loki/main/install_loki.sh | bash
+```
+
+#### Windows/Linux/MacOS (`PowerShell`)
+You can use the following command to run a PowerShell script that downloads and installs the latest version of `loki`
+for your OS (Windows/Linux/MacOS) and architecture (x86_64/arm64):
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -useb https://raw.githubusercontent.com/Dark-Alex-17/loki/main/scripts/install_loki.ps1 | iex"
+```
+
+### Manual
+Binaries are available on the [releases](https://github.com/Dark-Alex-17/loki/releases) page for the following platforms:
+
+| Platform       | Architecture(s) |
+|----------------|-----------------|
+| macOS          | x86_64, arm64   |
+| Linux GNU/MUSL | x86_64, aarch64 |
+| Windows        | x86_64, aarch64 |
+
+#### Windows Instructions
+To use a binary from the releases page on Windows, do the following:
+
+1. Download the latest [binary](https://github.com/Dark-Alex-17/loki/releases) for your OS.
+2. Use 7-Zip or TarTool to unpack the Tar file.
+3. Run the executable `loki.exe`!
+
+#### Linux/MacOS Instructions
+To use a binary from the releases page on Linux/MacOS, do the following:
+
+1. Download the latest [binary](https://github.com/Dark-Alex-17/loki/releases) for your OS.
+2. `cd` to the directory where you downloaded the binary.
+3. Extract the binary with `tar -C /usr/local/bin -xzf loki-<arch>.tar.gz` (Note: This may require `sudo`)
+4. Now you can run `loki`!
+
+## Updating
+Loki can update itself in place to the latest GitHub release. Run `loki --update`
+for the newest release, or `loki --update v0.4.0` for a specific version:
+
+```shell
+loki --update
+loki --update v0.4.0
+```
+
+The same is available from within the REPL via `.update` and `.update v0.4.0`.
+
+If Loki was installed with a package manager, prefer that package manager so its
+records stay in sync with the binary on disk; i.e. `brew upgrade loki` for Homebrew,
+or `cargo install --locked loki-ai` for Cargo.
+
+When Loki detects a package-manager install it prints a warning and asks for
+confirmation. In a non-interactive shell (no TTY), pass `--force` to update
+anyway:
+
+```shell
+loki --update --force
+```
+
+## Getting Started
+After installation, you can generate the configuration files and directories by simply running:
+
+```sh
+loki --info
+```
+
+Then, you need to set up the Loki vault by creating a vault password file. Loki will do this for you automatically and
+guide you through the process when you first attempt to access the vault. So, to get started, you can run:
+
+```sh
+loki --list-secrets
+```
+
+### Authentication
+Each client in your configuration needs authentication (with a few exceptions; e.g. ollama). Most clients use an API key
+(set via `api_key` in the config or through the [vault](https://github.com/Dark-Alex-17/loki/wiki/Vault)). For providers that support OAuth (e.g. Claude Pro/Max 
+subscribers, Google Gemini), you can authenticate with your existing subscription instead:
+
+```yaml
+# In your config.yaml
+clients:
+  - type: claude
+    name: my-claude-oauth
+    auth: oauth # Indicate you want to authenticate with OAuth instead of an API key
+```
+
+```sh
+loki --authenticate my-claude-oauth
+# Or via the REPL: .authenticate
+```
+
+For full details, see the [authentication documentation](https://github.com/Dark-Alex-17/loki/wiki/Clients#authentication).
+
+### Tab-Completions
+You can also enable tab completions to make using Loki easier. To do so, add the following to your shell profile:
+```shell
+# Bash
+# (add to: `~/.bashrc`)
+source <(COMPLETE=bash loki) 
+
+# Zsh
+# (add to: `~/.zshrc`)
+source <(COMPLETE=zsh loki)
+
+# Fish
+# (add to: `~/.config/fish/config.fish`)
+source <(COMPLETE=fish loki | psub)
+
+# Elvish
+# (add to: `~/.elvish/rc.elv`)
+eval (E:COMPLETE=elvish loki | slurp)
+
+# PowerShell
+# (add to: `$PROFILE`)
+$env:COMPLETE = "powershell"
+loki | Out-String | Invoke-Expression
+```
+
+### Shell Integration
+You can integrate Loki's Shell Assistant into your shell for enhanced command-line assistance. Add the code in the
+corresponding [shell integration script](./scripts/shell-integration) to your shell. Then, you can invoke Loki to convert natural language to 
+shell commands by pressing `Alt-e`. For example:
+
+```shell
+$ find all markdown files<Alt-e>
+# Will be converted to:
+find . -name "*.md"
+```
+
+## Configuration
+The location of the global Loki configuration varies between systems, so you can use the following command to find your
+`config.yaml` file:
+
+```shell
+loki --info | grep 'config_file' | awk '{print $2}'
+```
+
+The configuration file consists of a number of settings. To see a full example configuration file with every setting
+defined, refer to the [example configuration file](./config.example.yaml).
+
+### Default LLM
+The following settings are available to configure the default LLM that is used when you start Loki, and its
+hyperparameters:
+
+| Setting       | Description                                                                                                                                             |
+|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `model`       | The default LLM to use when no model is provided                                                                                                        |
+| `temperature` | The default `temperature` parameter for all models (0,1); Used unless explicitly overridden                                                             |
+| `top_p`       | The default `top_p` hyperparameter value to use for all models, with a range of (0,1) (or (0,2) for some models); <br>Used unless explicitly overridden |
+
+### CLI Behavior
+You can use the following settings to modify the behavior of Loki:
+
+| Setting       | Default Value | Description                                                                                                                         |
+|---------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------|
+| `stream`      | `true`        | Controls whether to use stream-style APIs when querying for completions from LLM providers                                          |
+| `save`        | `true`        | Controls whether to save each query/response to every model to `messages.md` for posterity; Useful for debugging                    |
+| `keybindings` | `emacs`       | Specifies which keybinding schema to use; can either be `emacs` or `vi`                                                             |
+| `editor`      | `null`        | What text editor Loki should use to edit the input buffer or session (e.g. `vim`, `emacs`, `nano`, `hx`); <br>Defaults to `$EDITOR` |
+| `wrap`        | `no`          | Controls whether text is wrapped (can be `no`, `auto`, or some `<max_width>`                                                        |
+| `wrap_code`   | `false`       | Enables or disables the wrapping of code blocks                                                                                     |
+
+### Preludes
+Preludes let you define the default behavior for the different operating modes of Loki. The available settings are
+shown below:
+
+| Setting         | Description                                                                                                                                                                                                                                                                                                 |
+|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `repl_prelude`  | This setting lets you specify a default `session` or `role` to use when starting Loki in [REPL](https://github.com/Dark-Alex-17/loki/wiki/REPL) mode. <br>Values can be <ul><li>`role:<name>` to define a role</li><li>`session:<name>` to define a session</li><li>`<session>:<role>` to define both a session and a role to use</li></ul> |
+| `cmd_prelude`   | This setting lets you specify a default `session` or `role` to use when running one-off queries in Loki via the CLI. <br>Values can be <ul><li>`role:<name>` to define a role</li><li>`session:<name>` to define a session</li><li>`<session>:<role>` to define both a session and a role to use</li></ul>  |
+| `agent_session` | This setting is used to specify a default session that all agents should start into, unless otherwise specified in the agent configuration. (e.g. `temp`, `default`)                                                                                                                                        |
+
+### Appearance
+The appearance of Loki can be modified using the following settings:
+
+| Setting       | Default Value | Description                                          |
+|---------------|---------------|------------------------------------------------------|
+| `highlight`   | `true`        | This setting enables or disables syntax highlighting |
+| `light_theme` | `false`       | This setting toggles light mode in Loki              |
+
+### Miscellaneous Settings
+| Setting              | Default Value | Description                                                                                                      |
+|----------------------|---------------|------------------------------------------------------------------------------------------------------------------|
+| `user_agent`         | `null`        | The name of the `User-Agent` that should be passed in the `User-Agent` header on all requests to model providers |
+| `save_shell_history` | `true`        | Enables or disables REPL command history                                                                         |
+
+---
+
+## History
+
+Loki began as a fork of [AIChat CLI](https://github.com/sigoden/aichat) and has since evolved into an independent project.
+
+See [CREDITS.md](./CREDITS.md) for full attribution and background.
+
+---
+
+## Creator
+* [Alex Clarke](https://github.com/Dark-Alex-17)

SECURITY.md

@@ -0,0 +1,15 @@
+# Security Policy
+
+## Supported Versions
+
+Only latest version of the software will be supported with security patches.
+
+| Version  | Supported          |
+| -------- | ------------------ |
+| latest   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+If you find a vulnerability, please reach out to me via email (alex.j.tusa@gmail.com).
+If you yourself decide you'd like to tackle a fix, please submit a PR with the fix and I'll review it as soon as 
+possible.

assets/agents/.shared/utils.sh

@@ -0,0 +1,319 @@
+#!/usr/bin/env bash
+# Shared Agent Utilities - Minimal, focused helper functions
+set -euo pipefail
+
+#######################
+## PROJECT DETECTION ##
+#######################
+
+# Cache file name for detected project info
+_LOKI_PROJECT_CACHE=".loki-project.json"
+
+# Read cached project detection if valid
+# Usage: _read_project_cache "/path/to/project"
+# Returns: cached JSON on stdout (exit 0) or nothing (exit 1)
+_read_project_cache() {
+  local dir="$1"
+  local cache_file="${dir}/${_LOKI_PROJECT_CACHE}"
+
+  if [[ -f "${cache_file}" ]]; then
+    local cached
+    cached=$(cat "${cache_file}" 2>/dev/null) || return 1
+    if echo "${cached}" | jq -e '.type and .build != null and .test != null and .check != null' &>/dev/null; then
+      echo "${cached}"
+      return 0
+    fi
+  fi
+  return 1
+}
+
+# Write project detection result to cache
+# Usage: _write_project_cache "/path/to/project" '{"type":"rust",...}'
+_write_project_cache() {
+  local dir="$1"
+  local json="$2"
+  local cache_file="${dir}/${_LOKI_PROJECT_CACHE}"
+
+  echo "${json}" > "${cache_file}" 2>/dev/null || true
+}
+
+_detect_heuristic() {
+  local dir="$1"
+
+  # Rust
+  if [[ -f "${dir}/Cargo.toml" ]]; then
+    echo '{"type":"rust","build":"cargo build","test":"cargo test","check":"cargo check"}'
+    return 0
+  fi
+
+  # Go
+  if [[ -f "${dir}/go.mod" ]]; then
+    echo '{"type":"go","build":"go build ./...","test":"go test ./...","check":"go vet ./..."}'
+    return 0
+  fi
+
+  # Node.JS/Deno/Bun
+  if [[ -f "${dir}/deno.json" ]] || [[ -f "${dir}/deno.jsonc" ]]; then
+    echo '{"type":"deno","build":"deno task build","test":"deno test","check":"deno lint"}'
+    return 0
+  fi
+
+  if [[ -f "${dir}/package.json" ]]; then
+    local pm="npm"
+
+    [[ -f "${dir}/bun.lockb" ]] || [[ -f "${dir}/bun.lock" ]] && pm="bun"
+    [[ -f "${dir}/pnpm-lock.yaml" ]] && pm="pnpm"
+    [[ -f "${dir}/yarn.lock" ]] && pm="yarn"
+
+    echo "{\"type\":\"nodejs\",\"build\":\"${pm} run build\",\"test\":\"${pm} test\",\"check\":\"${pm} run lint\"}"
+    return 0
+  fi
+
+  # Python
+  if [[ -f "${dir}/pyproject.toml" ]] || [[ -f "${dir}/setup.py" ]] || [[ -f "${dir}/setup.cfg" ]]; then
+    local test_cmd="pytest"
+    local check_cmd="ruff check ."
+
+    if [[ -f "${dir}/poetry.lock" ]]; then
+      test_cmd="poetry run pytest"
+      check_cmd="poetry run ruff check ."
+    elif [[ -f "${dir}/uv.lock" ]]; then
+      test_cmd="uv run pytest"
+      check_cmd="uv run ruff check ."
+    fi
+
+    echo "{\"type\":\"python\",\"build\":\"\",\"test\":\"${test_cmd}\",\"check\":\"${check_cmd}\"}"
+    return 0
+  fi
+
+  # JVM (Maven)
+  if [[ -f "${dir}/pom.xml" ]]; then
+    echo '{"type":"java","build":"mvn compile","test":"mvn test","check":"mvn verify"}'
+    return 0
+  fi
+
+  # JVM (Gradle)
+  if [[ -f "${dir}/build.gradle" ]] || [[ -f "${dir}/build.gradle.kts" ]]; then
+    local gw="gradle"
+    [[ -f "${dir}/gradlew" ]] && gw="./gradlew"
+    echo "{\"type\":\"java\",\"build\":\"${gw} build\",\"test\":\"${gw} test\",\"check\":\"${gw} check\"}"
+    return 0
+  fi
+
+  # .NET / C#
+  if compgen -G "${dir}/*.sln" &>/dev/null || compgen -G "${dir}/*.csproj" &>/dev/null; then
+    echo '{"type":"dotnet","build":"dotnet build","test":"dotnet test","check":"dotnet build --warnaserrors"}'
+    return 0
+  fi
+
+  # C/C++ (CMake)
+  if [[ -f "${dir}/CMakeLists.txt" ]]; then
+    echo '{"type":"cmake","build":"cmake --build build","test":"ctest --test-dir build","check":"cmake --build build"}'
+    return 0
+  fi
+
+  # Ruby
+  if [[ -f "${dir}/Gemfile" ]]; then
+    local test_cmd="bundle exec rake test"
+    [[ -f "${dir}/Rakefile" ]] && grep -q "rspec" "${dir}/Gemfile" 2>/dev/null && test_cmd="bundle exec rspec"
+    echo "{\"type\":\"ruby\",\"build\":\"\",\"test\":\"${test_cmd}\",\"check\":\"bundle exec rubocop\"}"
+    return 0
+  fi
+
+  # Elixir
+  if [[ -f "${dir}/mix.exs" ]]; then
+    echo '{"type":"elixir","build":"mix compile","test":"mix test","check":"mix credo"}'
+    return 0
+  fi
+
+  # PHP
+  if [[ -f "${dir}/composer.json" ]]; then
+    echo '{"type":"php","build":"","test":"./vendor/bin/phpunit","check":"./vendor/bin/phpstan analyse"}'
+    return 0
+  fi
+
+  # Swift
+  if [[ -f "${dir}/Package.swift" ]]; then
+    echo '{"type":"swift","build":"swift build","test":"swift test","check":"swift build"}'
+    return 0
+  fi
+
+  # Zig
+  if [[ -f "${dir}/build.zig" ]]; then
+    echo '{"type":"zig","build":"zig build","test":"zig build test","check":"zig build"}'
+    return 0
+  fi
+
+  # Generic build systems (last resort before LLM)
+  if [[ -f "${dir}/justfile" ]] || [[ -f "${dir}/Justfile" ]]; then
+    echo '{"type":"just","build":"just build","test":"just test","check":"just lint"}'
+    return 0
+  fi
+
+  if [[ -f "${dir}/Makefile" ]] || [[ -f "${dir}/makefile" ]] || [[ -f "${dir}/GNUmakefile" ]]; then
+    echo '{"type":"make","build":"make build","test":"make test","check":"make lint"}'
+    return 0
+  fi
+
+  return 1
+}
+
+# Gather lightweight evidence about a project for LLM analysis
+# Usage: _gather_project_evidence "/path/to/project"
+# Returns: evidence string on stdout
+_gather_project_evidence() {
+  local dir="$1"
+  local evidence=""
+
+  evidence+="Root files and directories:"$'\n'
+  evidence+=$(ls -1 "${dir}" 2>/dev/null | head -50)
+  evidence+=$'\n\n'
+
+  evidence+="File extension counts:"$'\n'
+  evidence+=$(find "${dir}" -type f \
+    -not -path '*/.git/*' \
+    -not -path '*/node_modules/*' \
+    -not -path '*/target/*' \
+    -not -path '*/dist/*' \
+    -not -path '*/__pycache__/*' \
+    -not -path '*/vendor/*' \
+    -not -path '*/.build/*' \
+    2>/dev/null \
+    | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10)
+  evidence+=$'\n\n'
+
+  local config_patterns=("*.toml" "*.yaml" "*.yml" "*.json" "*.xml" "*.gradle" "*.gradle.kts" "*.cabal" "*.pro" "Makefile" "justfile" "Justfile" "Dockerfile" "Taskfile*" "BUILD" "WORKSPACE" "flake.nix" "shell.nix" "default.nix")
+  local found_configs=0
+
+  for pattern in "${config_patterns[@]}"; do
+    if [[ ${found_configs} -ge 5 ]]; then
+      break
+    fi
+
+    local files
+    files=$(find "${dir}" -maxdepth 1 -name "${pattern}" -type f 2>/dev/null)
+
+    while IFS= read -r f; do
+      if [[ -n "${f}" && ${found_configs} -lt 5 ]]; then
+        local basename
+        basename=$(basename "${f}")
+        evidence+="--- ${basename} (first 30 lines) ---"$'\n'
+        evidence+=$(head -30 "${f}" 2>/dev/null)
+        evidence+=$'\n\n'
+        found_configs=$((found_configs + 1))
+      fi
+    done <<< "${files}"
+  done
+
+  echo "${evidence}"
+}
+
+# LLM-based project detection fallback
+# Usage: _detect_with_llm "/path/to/project"
+# Returns: JSON on stdout or empty (exit 1)
+_detect_with_llm() {
+  local dir="$1"
+  local evidence
+  evidence=$(_gather_project_evidence "${dir}")
+  local prompt
+  prompt=$(cat <<-EOF
+
+		Analyze this project directory and determine the project type, primary language, and the correct shell commands to build, test, and check (lint/typecheck) it.
+
+		EOF
+	)
+  prompt+=$'\n'"${evidence}"$'\n'
+  prompt+=$(cat <<-EOF
+
+		Respond with ONLY a valid JSON object. No markdown fences, no explanation, no extra text.
+		The JSON must have exactly these 4 keys:
+		{"type":"<language>","build":"<build command>","test":"<test command>","check":"<lint or typecheck command>"}
+
+		Rules:
+		- "type" must be a single lowercase word (e.g. rust, go, python, nodejs, java, ruby, elixir, cpp, c, zig, haskell, scala, kotlin, dart, swift, php, dotnet, etc.)
+		- If a command doesn't apply to this project, use an empty string, ""
+		- Use the most standard/common commands for the detected ecosystem
+		- If you detect a package manager lockfile, use that package manager (e.g. pnpm over npm)
+		EOF
+	)
+
+  local llm_response
+  llm_response=$(loki --no-stream "${prompt}" 2>/dev/null) || return 1
+
+  llm_response=$(echo "${llm_response}" | sed 's/^```json//;s/^```//;s/```$//' | tr -d '\n' | sed 's/^[[:space:]]*//')
+  llm_response=$(echo "${llm_response}" | grep -o '{[^}]*}' | head -1)
+
+  if echo "${llm_response}" | jq -e '.type and .build != null and .test != null and .check != null' &>/dev/null; then
+    echo "${llm_response}" | jq -c '{type: (.type // "unknown"), build: (.build // ""), test: (.test // ""), check: (.check // "")}'
+    return 0
+  fi
+
+  return 1
+}
+
+# Detect project type and return build/test commands
+# Uses: cached result -> fast heuristics -> LLM fallback
+detect_project() {
+  local dir="${1:-.}"
+
+  local cached
+  if cached=$(_read_project_cache "${dir}"); then
+    echo "${cached}" | jq -c '{type, build, test, check}'
+    return 0
+  fi
+
+  local result
+  if result=$(_detect_heuristic "${dir}"); then
+    local enriched
+    enriched=$(echo "${result}" | jq -c '. + {"_detected_by":"heuristic","_cached_at":"'"$(date -Iseconds)"'"}')
+
+    _write_project_cache "${dir}" "${enriched}"
+
+    echo "${result}"
+    return 0
+  fi
+
+  if result=$(_detect_with_llm "${dir}"); then
+    local enriched
+    enriched=$(echo "${result}" | jq -c '. + {"_detected_by":"llm","_cached_at":"'"$(date -Iseconds)"'"}')
+
+    _write_project_cache "${dir}" "${enriched}"
+
+    echo "${result}"
+    return 0
+  fi
+
+  echo '{"type":"unknown","build":"","test":"","check":""}'
+}
+
+###########################
+## FILE SEARCH UTILITIES ##
+###########################
+
+_search_files() {
+  local pattern="$1"
+  local dir="${2:-.}"
+  
+  find "${dir}" -type f -name "${pattern}" \
+    -not -path '*/target/*' \
+    -not -path '*/node_modules/*' \
+    -not -path '*/.git/*' \
+    -not -path '*/dist/*' \
+    -not -path '*/__pycache__/*' \
+    2>/dev/null | head -25
+}
+
+get_tree() {
+  local dir="${1:-.}"
+  local depth="${2:-3}"
+  
+  if command -v tree &>/dev/null; then
+    tree -L "${depth}" --noreport -I 'node_modules|target|dist|.git|__pycache__|*.pyc' "${dir}" 2>/dev/null || find "${dir}" -maxdepth "${depth}" -type f | head -50
+  else
+    find "${dir}" -maxdepth "${depth}" -type f \
+      -not -path '*/target/*' \
+      -not -path '*/node_modules/*' \
+      -not -path '*/.git/*' \
+      2>/dev/null | head -50
+  fi
+}

assets/agents/code-reviewer/README.md

@@ -0,0 +1,36 @@
+# Code Reviewer
+
+A CodeRabbit-style code review orchestrator that coordinates per-file reviews and synthesizes findings into a unified 
+report.
+
+This agent acts as the manager for the review process, delegating actual file analysis to **[File Reviewer](../file-reviewer/README.md)** 
+agents while handling coordination and final reporting.
+
+## Features
+
+- 🤖 **Orchestration**: Spawns parallel reviewers for each changed file.
+- 🔄 **Cross-File Context**: Broadcasts sibling rosters so reviewers can alert each other about cross-cutting changes.
+- 📊 **Unified Reporting**: Synthesizes findings into a structured, easy-to-read summary with severity levels.
+- ⚡ **Parallel Execution**: Runs reviews concurrently for maximum speed.
+
+## Pro-Tip: Use an IDE MCP Server for Improved Performance
+Many modern IDEs now include MCP servers that let LLMs perform operations within the IDE itself and use IDE tools. Using
+an IDE's MCP server dramatically improves the performance of coding agents. So if you have an IDE, try adding that MCP
+server to your config (see the [MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md) to see how to configure
+them), and modify the agent definition to look like this:
+
+```yaml
+# ...
+
+mcp_servers:
+  - jetbrains # The name of your configured IDE MCP server
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+#  - execute_command.sh
+
+# ...
+```
+

assets/agents/code-reviewer/config.yaml

@@ -0,0 +1,127 @@
+name: code-reviewer
+description: CodeRabbit-style code reviewer - spawns per-file reviewers, synthesizes findings
+version: 1.0.0
+temperature: 0.1
+
+auto_continue: true
+max_auto_continues: 20
+inject_todo_instructions: true
+
+can_spawn_agents: true
+max_concurrent_agents: 10
+max_agent_depth: 2
+
+variables:
+  - name: project_dir
+    description: Project directory to review
+    default: '.'
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - execute_command.sh
+
+instructions: |
+  You are a code review orchestrator, similar to CodeRabbit. You coordinate per-file reviews and produce a unified report.
+
+  ## Workflow
+
+  1. **Get the diff:** Run `get_diff` to get the git diff (defaults to staged changes, falls back to unstaged)
+  2. **Parse changed files:** Extract the list of files from the diff
+  3. **Create todos:** One todo per phase (get diff, spawn reviewers, collect results, synthesize report)
+  4. **Spawn file-reviewers:** One `file-reviewer` agent per changed file, in parallel
+  5. **Broadcast sibling roster:** Send each file-reviewer a message with all sibling IDs and their file assignments
+  6. **Collect all results:** Wait for each file-reviewer to complete
+  7. **Synthesize:** Combine all findings into a CodeRabbit-style report
+
+  ## Spawning File Reviewers
+
+  For each changed file, spawn a file-reviewer with a prompt containing:
+  - The file path
+  - The relevant diff hunk(s) for that file
+  - Instructions to review it
+
+  ```
+  agent__spawn --agent file-reviewer --prompt "Review the following diff for <file_path>:
+
+  <diff content for this file>
+
+  Focus on bugs, security issues, logic errors, and style. Use the severity format (🔴🟡🟢💡).
+  End with REVIEW_COMPLETE."
+  ```
+
+  ## Sibling Roster Broadcast
+
+  After spawning ALL file-reviewers (collecting their IDs), send each one a message with the roster:
+
+  ```
+  agent__send_message --to <agent_id> --message "SIBLING_ROSTER:
+  - <agent_id_1>: reviewing <file_1>
+  - <agent_id_2>: reviewing <file_2>
+  ...
+  Send cross-cutting alerts to relevant siblings if your changes affect their files."
+  ```
+
+  ## Diff Parsing
+
+  Split the diff by file. Each file's diff starts with `diff --git a/<path> b/<path>`. Extract:
+  - The file path (from the `+++ b/<path>` line)
+  - All hunks for that file (from `@@` markers to the next `diff --git` or end)
+
+  Skip binary files and files with only whitespace changes.
+
+  ## Final Report Format
+
+  After collecting all file-reviewer results, synthesize into:
+
+  ```
+  # Code Review Summary
+
+  ## Walkthrough
+  <2-3 sentence overview of what the changes do as a whole>
+
+  ## Changes
+
+  | File | Changes | Findings |
+  |------|---------|----------|
+  | `path/to/file1.rs` | <brief description> | 🔴 1 🟡 2 🟢 1 |
+  | `path/to/file2.rs` | <brief description> | 🟢 2 💡 1 |
+
+  ## Detailed Findings
+
+  ### `path/to/file1.rs`
+  <paste file-reviewer's findings here, cleaned up>
+
+  ### `path/to/file2.rs`
+  <paste file-reviewer's findings here, cleaned up>
+
+  ## Cross-File Concerns
+  <any cross-cutting issues identified by the teammate pattern>
+
+  ---
+  *Reviewed N files, found X critical, Y warnings, Z suggestions, W nitpicks*
+  ```
+
+  ## Edge Cases
+
+  - **Single file changed:** Still spawn one file-reviewer (for consistency), skip roster broadcast
+  - **Too many files (>10):** Group small files (< 20 lines changed) and review them together
+  - **No changes found:** Report "No changes to review" and exit
+  - **Binary files:** Skip with a note in the summary
+
+  ## Rules
+
+  1. **Always use `get_diff` first:** Don't assume what changed
+  2. **Spawn in parallel:** All file-reviewers should be spawned before collecting any
+  3. **Don't review code yourself:** Delegate ALL review work to file-reviewers
+  4. **Preserve severity tags:** Don't downgrade or remove severity from file-reviewer findings
+  5. **Include ALL findings:** Don't summarize away specific issues
+
+  ## Context
+  - Project: {{project_dir}}
+  - CWD: {{__cwd__}}
+  - Shell: {{__shell__}}
+  
+  ## Available Tools:
+  {{__tools__}}

assets/agents/code-reviewer/tools.sh

@@ -0,0 +1,478 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Code review orchestrator tools
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# @cmd Get git diff for code review. Returns staged changes, or unstaged if nothing is staged, or HEAD~1 diff if working tree is clean.
+# @option --base Optional base ref to diff against (e.g., "main", "HEAD~3", a commit SHA)
+get_diff() {
+  local project_dir
+  project_dir=$(_project_dir)
+  # shellcheck disable=SC2154
+  local base="${argc_base:-}"
+
+  local diff_output=""
+
+  if [[ -n "${base}" ]]; then
+    diff_output=$(cd "${project_dir}" && git diff "${base}" 2>&1) || true
+  else
+    diff_output=$(cd "${project_dir}" && git diff --cached 2>&1) || true
+
+    if [[ -z "${diff_output}" ]]; then
+      diff_output=$(cd "${project_dir}" && git diff 2>&1) || true
+    fi
+
+    if [[ -z "${diff_output}" ]]; then
+      diff_output=$(cd "${project_dir}" && git diff HEAD~1 2>&1) || true
+    fi
+  fi
+
+  if [[ -z "${diff_output}" ]]; then
+    warn "No changes found to review" >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  local file_count
+  file_count=$(echo "${diff_output}" | grep -c '^diff --git' || true)
+
+  {
+    info "Diff contains changes to ${file_count} file(s)"
+    echo ""
+    echo "${diff_output}"
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Get list of changed files with stats
+# @option --base Optional base ref to diff against
+get_changed_files() {
+  local project_dir
+  project_dir=$(_project_dir)
+  local base="${argc_base:-}"
+
+  local stat_output=""
+
+  if [[ -n "${base}" ]]; then
+    stat_output=$(cd "${project_dir}" && git diff --stat "${base}" 2>&1) || true
+  else
+    stat_output=$(cd "${project_dir}" && git diff --cached --stat 2>&1) || true
+
+    if [[ -z "${stat_output}" ]]; then
+      stat_output=$(cd "${project_dir}" && git diff --stat 2>&1) || true
+    fi
+
+    if [[ -z "${stat_output}" ]]; then
+      stat_output=$(cd "${project_dir}" && git diff --stat HEAD~1 2>&1) || true
+    fi
+  fi
+
+  if [[ -z "${stat_output}" ]]; then
+    warn "No changes found" >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  {
+    info "Changed files:"
+    echo ""
+    echo "${stat_output}"
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Get project structure and type information
+get_project_info() {
+  local project_dir
+  project_dir=$(_project_dir)
+
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  {
+    info "Project: ${project_dir}"
+    echo "Type: $(echo "${project_info}" | jq -r '.type')"
+    echo ""
+    get_tree "${project_dir}" 2
+  } >> "$LLM_OUTPUT"
+}
+
+# ARGC-BUILD {
+# This block was generated by argc (https://github.com/sigoden/argc).
+# Modifying it manually is not recommended
+
+_argc_run() {
+    if [[ "${1:-}" == "___internal___" ]]; then
+        _argc_die "error: unsupported ___internal___ command"
+    fi
+    if [[ "${OS:-}" == "Windows_NT" ]] && [[ -n "${MSYSTEM:-}" ]]; then
+        set -o igncr
+    fi
+    argc__args=("$(basename "$0" .sh)" "$@")
+    argc__positionals=()
+    _argc_index=1
+    _argc_len="${#argc__args[@]}"
+    _argc_tools=()
+    _argc_parse
+    if [ -n "${argc__fn:-}" ]; then
+        $argc__fn "${argc__positionals[@]}"
+    fi
+}
+
+_argc_usage() {
+    cat <<-'EOF'
+Code review orchestrator tools
+
+USAGE:  <COMMAND>
+
+COMMANDS:
+  get_diff           Get git diff for code review. Returns staged changes, or unstaged if nothing is staged, or HEAD~1 diff if working tree is clean. [aliases: get-diff]
+  get_changed_files  Get list of changed files with stats [aliases: get-changed-files]
+  get_project_info   Get project structure and type information [aliases: get-project-info]
+
+ENVIRONMENTS:
+  LLM_OUTPUT                 [default: /dev/stdout]
+  LLM_AGENT_VAR_PROJECT_DIR  [default: .]
+EOF
+    exit
+}
+
+_argc_version() {
+    echo  0.0.0
+    exit
+}
+
+_argc_parse() {
+    local _argc_key _argc_action
+    local _argc_subcmds="get_diff, get-diff, get_changed_files, get-changed-files, get_project_info, get-project-info"
+    while [[ $_argc_index -lt $_argc_len ]]; do
+        _argc_item="${argc__args[_argc_index]}"
+        _argc_key="${_argc_item%%=*}"
+        case "$_argc_key" in
+        --help | -help | -h)
+            _argc_usage
+            ;;
+        --version | -version | -V)
+            _argc_version
+            ;;
+        --)
+            _argc_dash="${#argc__positionals[@]}"
+            argc__positionals+=("${argc__args[@]:$((_argc_index + 1))}")
+            _argc_index=$_argc_len
+            break
+            ;;
+        get_diff | get-diff)
+            _argc_index=$((_argc_index + 1))
+            _argc_action=_argc_parse_get_diff
+            break
+            ;;
+        get_changed_files | get-changed-files)
+            _argc_index=$((_argc_index + 1))
+            _argc_action=_argc_parse_get_changed_files
+            break
+            ;;
+        get_project_info | get-project-info)
+            _argc_index=$((_argc_index + 1))
+            _argc_action=_argc_parse_get_project_info
+            break
+            ;;
+        help)
+            local help_arg="${argc__args[$((_argc_index + 1))]:-}"
+            case "$help_arg" in
+            get_diff | get-diff)
+                _argc_usage_get_diff
+                ;;
+            get_changed_files | get-changed-files)
+                _argc_usage_get_changed_files
+                ;;
+            get_project_info | get-project-info)
+                _argc_usage_get_project_info
+                ;;
+            "")
+                _argc_usage
+                ;;
+            *)
+                _argc_die "error: invalid value \`$help_arg\` for \`<command>\`"$'\n'"  [possible values: $_argc_subcmds]"
+                ;;
+            esac
+            ;;
+        *)
+            _argc_die "error: \`\` requires a subcommand but one was not provided"$'\n'"  [subcommands: $_argc_subcmds]"
+            ;;
+        esac
+    done
+    if [[ -n "${_argc_action:-}" ]]; then
+        $_argc_action
+    else
+        _argc_usage
+    fi
+}
+
+_argc_usage_get_diff() {
+    cat <<-'EOF'
+Get git diff for code review. Returns staged changes, or unstaged if nothing is staged, or HEAD~1 diff if working tree is clean.
+
+USAGE:  get_diff [OPTIONS]
+
+OPTIONS:
+      --base <BASE>  Optional base ref to diff against (e.g., "main", "HEAD~3", a commit SHA)
+  -h, --help         Print help
+
+ENVIRONMENTS:
+  LLM_OUTPUT                 [default: /dev/stdout]
+  LLM_AGENT_VAR_PROJECT_DIR  [default: .]
+EOF
+    exit
+}
+
+_argc_parse_get_diff() {
+    local _argc_key _argc_action
+    local _argc_subcmds=""
+    while [[ $_argc_index -lt $_argc_len ]]; do
+        _argc_item="${argc__args[_argc_index]}"
+        _argc_key="${_argc_item%%=*}"
+        case "$_argc_key" in
+        --help | -help | -h)
+            _argc_usage_get_diff
+            ;;
+        --)
+            _argc_dash="${#argc__positionals[@]}"
+            argc__positionals+=("${argc__args[@]:$((_argc_index + 1))}")
+            _argc_index=$_argc_len
+            break
+            ;;
+        --base)
+            _argc_take_args "--base <BASE>" 1 1 "-" ""
+            _argc_index=$((_argc_index + _argc_take_args_len + 1))
+            if [[ -z "${argc_base:-}" ]]; then
+                argc_base="${_argc_take_args_values[0]:-}"
+            else
+                _argc_die "error: the argument \`--base\` cannot be used multiple times"
+            fi
+            ;;
+        *)
+            if _argc_maybe_flag_option "-" "$_argc_item"; then
+                _argc_die "error: unexpected argument \`$_argc_key\` found"
+            fi
+            argc__positionals+=("$_argc_item")
+            _argc_index=$((_argc_index + 1))
+            ;;
+        esac
+    done
+    if [[ -n "${_argc_action:-}" ]]; then
+        $_argc_action
+    else
+        argc__fn=get_diff
+        if [[ "${argc__positionals[0]:-}" == "help" ]] && [[ "${#argc__positionals[@]}" -eq 1 ]]; then
+            _argc_usage_get_diff
+        fi
+        if [[ -z "${LLM_OUTPUT:-}" ]]; then
+            export LLM_OUTPUT=/dev/stdout
+        fi
+        if [[ -z "${LLM_AGENT_VAR_PROJECT_DIR:-}" ]]; then
+            export LLM_AGENT_VAR_PROJECT_DIR=.
+        fi
+    fi
+}
+
+_argc_usage_get_changed_files() {
+    cat <<-'EOF'
+Get list of changed files with stats
+
+USAGE:  get_changed_files [OPTIONS]
+
+OPTIONS:
+      --base <BASE>  Optional base ref to diff against
+  -h, --help         Print help
+
+ENVIRONMENTS:
+  LLM_OUTPUT                 [default: /dev/stdout]
+  LLM_AGENT_VAR_PROJECT_DIR  [default: .]
+EOF
+    exit
+}
+
+_argc_parse_get_changed_files() {
+    local _argc_key _argc_action
+    local _argc_subcmds=""
+    while [[ $_argc_index -lt $_argc_len ]]; do
+        _argc_item="${argc__args[_argc_index]}"
+        _argc_key="${_argc_item%%=*}"
+        case "$_argc_key" in
+        --help | -help | -h)
+            _argc_usage_get_changed_files
+            ;;
+        --)
+            _argc_dash="${#argc__positionals[@]}"
+            argc__positionals+=("${argc__args[@]:$((_argc_index + 1))}")
+            _argc_index=$_argc_len
+            break
+            ;;
+        --base)
+            _argc_take_args "--base <BASE>" 1 1 "-" ""
+            _argc_index=$((_argc_index + _argc_take_args_len + 1))
+            if [[ -z "${argc_base:-}" ]]; then
+                argc_base="${_argc_take_args_values[0]:-}"
+            else
+                _argc_die "error: the argument \`--base\` cannot be used multiple times"
+            fi
+            ;;
+        *)
+            if _argc_maybe_flag_option "-" "$_argc_item"; then
+                _argc_die "error: unexpected argument \`$_argc_key\` found"
+            fi
+            argc__positionals+=("$_argc_item")
+            _argc_index=$((_argc_index + 1))
+            ;;
+        esac
+    done
+    if [[ -n "${_argc_action:-}" ]]; then
+        $_argc_action
+    else
+        argc__fn=get_changed_files
+        if [[ "${argc__positionals[0]:-}" == "help" ]] && [[ "${#argc__positionals[@]}" -eq 1 ]]; then
+            _argc_usage_get_changed_files
+        fi
+        if [[ -z "${LLM_OUTPUT:-}" ]]; then
+            export LLM_OUTPUT=/dev/stdout
+        fi
+        if [[ -z "${LLM_AGENT_VAR_PROJECT_DIR:-}" ]]; then
+            export LLM_AGENT_VAR_PROJECT_DIR=.
+        fi
+    fi
+}
+
+_argc_usage_get_project_info() {
+    cat <<-'EOF'
+Get project structure and type information
+
+USAGE:  get_project_info
+
+ENVIRONMENTS:
+  LLM_OUTPUT                 [default: /dev/stdout]
+  LLM_AGENT_VAR_PROJECT_DIR  [default: .]
+EOF
+    exit
+}
+
+_argc_parse_get_project_info() {
+    local _argc_key _argc_action
+    local _argc_subcmds=""
+    while [[ $_argc_index -lt $_argc_len ]]; do
+        _argc_item="${argc__args[_argc_index]}"
+        _argc_key="${_argc_item%%=*}"
+        case "$_argc_key" in
+        --help | -help | -h)
+            _argc_usage_get_project_info
+            ;;
+        --)
+            _argc_dash="${#argc__positionals[@]}"
+            argc__positionals+=("${argc__args[@]:$((_argc_index + 1))}")
+            _argc_index=$_argc_len
+            break
+            ;;
+        *)
+            argc__positionals+=("$_argc_item")
+            _argc_index=$((_argc_index + 1))
+            ;;
+        esac
+    done
+    if [[ -n "${_argc_action:-}" ]]; then
+        $_argc_action
+    else
+        argc__fn=get_project_info
+        if [[ "${argc__positionals[0]:-}" == "help" ]] && [[ "${#argc__positionals[@]}" -eq 1 ]]; then
+            _argc_usage_get_project_info
+        fi
+        if [[ -z "${LLM_OUTPUT:-}" ]]; then
+            export LLM_OUTPUT=/dev/stdout
+        fi
+        if [[ -z "${LLM_AGENT_VAR_PROJECT_DIR:-}" ]]; then
+            export LLM_AGENT_VAR_PROJECT_DIR=.
+        fi
+    fi
+}
+
+_argc_take_args() {
+    _argc_take_args_values=()
+    _argc_take_args_len=0
+    local param="$1" min="$2" max="$3" signs="$4" delimiter="$5"
+    if [[ "$min" -eq 0 ]] && [[ "$max" -eq 0 ]]; then
+        return
+    fi
+    local _argc_take_index=$((_argc_index + 1)) _argc_take_value
+    if [[ "$_argc_item" == *=* ]]; then
+        _argc_take_args_values=("${_argc_item##*=}")
+    else
+        while [[ $_argc_take_index -lt $_argc_len ]]; do
+            _argc_take_value="${argc__args[_argc_take_index]}"
+            if _argc_maybe_flag_option "$signs" "$_argc_take_value"; then
+                if [[ "${#_argc_take_value}" -gt 1 ]]; then
+                    break
+                fi
+            fi
+            _argc_take_args_values+=("$_argc_take_value")
+            _argc_take_args_len=$((_argc_take_args_len + 1))
+            if [[ "$_argc_take_args_len" -ge "$max" ]]; then
+                break
+            fi
+            _argc_take_index=$((_argc_take_index + 1))
+        done
+    fi
+    if [[ "${#_argc_take_args_values[@]}" -lt "$min" ]]; then
+        _argc_die "error: incorrect number of values for \`$param\`"
+    fi
+    if [[ -n "$delimiter" ]] && [[ "${#_argc_take_args_values[@]}" -gt 0 ]]; then
+        local item values arr=()
+        for item in "${_argc_take_args_values[@]}"; do
+            IFS="$delimiter" read -r -a values <<<"$item"
+            arr+=("${values[@]}")
+        done
+        _argc_take_args_values=("${arr[@]}")
+    fi
+}
+
+_argc_maybe_flag_option() {
+    local signs="$1" arg="$2"
+    if [[ -z "$signs" ]]; then
+        return 1
+    fi
+    local cond=false
+    if [[ "$signs" == *"+"* ]]; then
+        if [[ "$arg" =~ ^\+[^+].* ]]; then
+            cond=true
+        fi
+    elif [[ "$arg" == -* ]]; then
+        if (( ${#arg} < 3 )) || [[ ! "$arg" =~ ^---.* ]]; then
+            cond=true
+        fi
+    fi
+    if [[ "$cond" == "false" ]]; then
+        return 1
+    fi
+    local value="${arg%%=*}"
+    if [[ "$value" =~ [[:space:]] ]]; then
+        return 1
+    fi
+    return 0
+}
+
+_argc_die() {
+    if [[ $# -eq 0 ]]; then
+        cat
+    else
+        echo "$*" >&2
+    fi
+    exit 1
+}
+
+_argc_run "$@"
+
+# ARGC-BUILD }

assets/agents/coder/README.md

@@ -0,0 +1,82 @@
+# Coder
+
+A graph-based implementation agent. Plans, implements, and runs build +
+tests in a bounded fix-loop until verified. Designed to be delegated to by
+the **[Sisyphus](../sisyphus/README.md)** agent.
+
+Coder is a [graph agent](https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents): its workflow is
+defined declaratively in `graph.yaml`, with verification and the
+implement-fix loop enforced as graph edges rather than prose.
+
+## Workflow
+
+```
+analyze_request (llm + output_schema)   plan + complexity extraction
+        ↓
+route_complexity (script)               opt-out approval gate (complexity ≥ 7)
+        ↓
+gate_approval (approval, optional)
+        ↓
+implement (llm + fs tools)              actual file edits
+        ↓
+verify_build (script)
+        ↓
+verify_tests (script)
+        ↓
+fix_loop_gate (script)                  back-edge to implement (bounded)
+        ↓
+end_success / end_rejected / end_failure
+```
+
+End nodes emit one of three sentinel outcomes for the caller:
+
+- `CODER_COMPLETE` — build and tests passed.
+- `CODER_REJECTED` — user rejected the plan at the approval gate.
+- `CODER_FAILED` — fix-loop exhausted; build/tests still failing.
+
+## Tuning
+
+The agent's `project_dir` is exposed via the standard `variables:` block,
+so it accepts the runtime override flag:
+
+```sh
+# Invoke from inside the project (project_dir defaults to ".")
+cd /path/to/your/project
+loki -a coder "Add a foo() function..."
+
+# Or invoke from anywhere with an explicit override
+loki -a coder --agent-variable project_dir /path/to/your/project "Add..."
+```
+
+`graph.yaml` `initial_state` exposes:
+
+- `max_fix_attempts` (default `3`) — fix-loop budget before `end_failure`.
+
+Environment overrides honored by the script nodes:
+
+- `BUILD_CMD` — skip project-type detection for the build/check command.
+- `TEST_CMD` — skip detection for tests.
+- `CODER_AUTOAPPROVE=1` — bypass the approval gate (for non-interactive runs
+  where complexity might trip the gate).
+
+## Pro-Tip: IDE MCP Server
+
+Modern IDEs (JetBrains, VS Code, Cursor, Zed, etc.) expose MCP servers
+that let LLMs use IDE tools directly. To wire one in, edit `graph.yaml`:
+
+```yaml
+mcp_servers:
+  - your-ide-mcp-server
+
+global_tools:
+  # Keep read-only fs tools for files outside the IDE project
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+#  - fs_write.sh
+#  - fs_patch.sh
+  - execute_command.sh
+```
+
+Then add the MCP server's write/patch tools to the `implement` node's
+`tools:` whitelist.

assets/agents/coder/graph.yaml

@@ -0,0 +1,278 @@
+name: coder
+description: |
+  Implementation agent. Plans, implements, and runs build + tests in a
+  bounded fix-loop until verified. Designed to be delegated to by sisyphus.
+version: "1.0"
+
+temperature: 0.1
+
+global_tools:
+  - fs_cat.sh
+  - fs_ls.sh
+  - fs_write.sh
+  - fs_patch.sh
+  - execute_command.sh
+
+variables:
+  - name: project_dir
+    description: |
+      Absolute path to the project directory. Defaults to "." which is the
+      directory you invoked `loki` from. Override at runtime with
+      `loki -a coder --agent-variable project_dir /abs/path "..."`.
+    default: "."
+
+settings:
+  max_loop_iterations: 20
+  log_state_snapshots: true
+  validate_before_run: true
+  timeout: 1800
+
+initial_state:
+  project_dir: ""
+  fix_attempts: 0
+  max_fix_attempts: 3
+  fix_instructions: ""
+  build_output: ""
+  tests_output: ""
+  last_node_output: ""
+  plan_summary: ""
+  files_to_modify: []
+  files_to_create: []
+  risks: []
+  complexity_score: 0
+
+start: resolve_paths
+
+nodes:
+  resolve_paths:
+    id: resolve_paths
+    type: script
+    description: Resolve project_dir to an absolute path from the agent variable
+    script: scripts/resolve_paths.sh
+    timeout: 5
+    fallback: end_failure
+
+  analyze_request:
+    id: analyze_request
+    type: llm
+    description: Extract a structured plan and complexity score from the orchestrator's prompt
+    instructions: |
+      You are a senior engineer's planning assistant. Read the orchestrator's
+      request and emit a structured plan. You only plan. You never edit files.
+
+      Score complexity from 1 to 10:
+        1-3: trivial - single file, <=20 lines changed, obvious approach
+        4-6: moderate - 2-5 files, clear approach, some pattern matching
+        7-10: complex - multi-component, ambiguous tradeoffs, refactoring,
+              or wide blast radius
+
+      Be specific in `files_to_modify` and `files_to_create`. All paths
+      MUST be absolute. The project root is {{project_dir}}. Prefer paths
+      like "{{project_dir}}/src/foo.rs" over "src/foo.rs". The implementer
+      uses these paths directly with fs_write and fs_patch tools, which
+      resolve relative paths against the loki invocation directory (NOT
+      the project dir). Empty arrays are fine if no files in that category.
+
+      `risks` is a list of short strings. Anything that could derail the
+      implementation: unknown dependencies, brittle tests, blast radius,
+      etc. Empty list is fine.
+
+      Project directory: {{project_dir}}
+    prompt: "{{initial_prompt}}"
+    tools: []
+    output_schema:
+      type: object
+      properties:
+        plan_summary:
+          type: string
+          description: 1-3 sentences summarizing what will be done
+        files_to_modify:
+          type: array
+          items: {type: string}
+        files_to_create:
+          type: array
+          items: {type: string}
+        complexity_score:
+          type: integer
+          minimum: 1
+          maximum: 10
+        risks:
+          type: array
+          items: {type: string}
+      required: [plan_summary, files_to_modify, files_to_create, complexity_score, risks]
+    state_updates:
+      last_node_output: "{{output}}"
+    fallback: end_failure
+    next: route_complexity
+
+  route_complexity:
+    id: route_complexity
+    type: script
+    description: Route to approval gate for complex plans; skip otherwise
+    script: scripts/route_complexity.sh
+    timeout: 5
+    fallback: implement
+
+  gate_approval:
+    id: gate_approval
+    type: approval
+    description: Optional human checkpoint for high-complexity plans
+    question: |
+      ## Plan
+      {{plan_summary}}
+
+      ## Files to modify
+      {{files_to_modify}}
+
+      ## Files to create
+      {{files_to_create}}
+
+      ## Risks
+      {{risks}}
+
+      Complexity: {{complexity_score}}/10
+
+      Approve this plan?
+    options:
+      - "yes"
+      - "no"
+    routes:
+      "yes": implement
+      "no": end_rejected
+    on_other: end_rejected
+
+  implement:
+    id: implement
+    type: llm
+    description: Write code via fs tools. Bounded tool-call loop.
+    instructions: |
+      You are a senior engineer. Implement the plan by writing code via
+      tools. Follow existing patterns in the codebase.
+
+      ## Writing code
+
+      1. Use `fs_patch` for surgical edits to existing files.
+      2. Use `fs_write` for new files or full rewrites.
+      3. NEVER output code to chat. Always use tools.
+      4. ALWAYS pass ABSOLUTE paths to fs_write and fs_patch. Relative
+         paths resolve against the loki invocation directory (not the
+         project dir), which is rarely what you want. The project root
+         is {{project_dir}}.
+
+      ## File reading
+
+      1. Use `execute_command` to grep/find:
+         `execute_command --command "grep -rn 'fn handle_request' --include='*.rs' ."`
+         `execute_command --command "find . -name '*.rs' -not -path '*/target/*'"`
+      2. Read only what you need:
+         `fs_cat --path "src/main.rs" --offset 50 --limit 30`
+      3. Never read entire large files. Use offset/limit.
+      4. Use `fs_ls` to list directory contents.
+
+      ## Pattern matching
+
+      Before writing ANY file:
+      1. Find a similar existing file (grep, then read).
+      2. Match its style: imports, naming, structure, error handling.
+      3. Follow the same patterns exactly. Do not invent new ones.
+
+      ## Fix loop
+
+      If the "Fix loop status" section in your user prompt is non-empty,
+      the previous attempt failed verification. Read the error, identify
+      the minimal fix, apply it. Do not refactor while fixing.
+
+      ## Rules
+
+      1. Match existing patterns - read examples first.
+      2. Minimal changes - implement only what's asked.
+      3. Never suppress errors (`as any`, `@ts-ignore`, `#[allow(...)]`
+         on unfamiliar lints, etc.).
+      4. No dead code, no commented-out blocks, no premature abstractions.
+      5. End your turn when editing is done. The graph runs verification next.
+
+      Project directory: {{project_dir}}
+    prompt: |
+      ## Plan summary
+      {{plan_summary}}
+
+      ## Files involved
+      - Modify: {{files_to_modify}}
+      - Create: {{files_to_create}}
+
+      ## Original request from the orchestrator
+      {{initial_prompt}}
+
+      ## Fix loop status
+      {{fix_instructions}}
+    tools:
+      - fs_cat
+      - fs_ls
+      - fs_write
+      - fs_patch
+      - execute_command
+    max_iterations: 30
+    state_updates:
+      last_node_output: "{{output}}"
+    fallback: end_failure
+    next: verify_build
+
+  verify_build:
+    id: verify_build
+    type: script
+    description: Run the project's check/build command. Routes to verify_tests on success, fix_loop_gate on failure.
+    script: scripts/verify_build.sh
+    timeout: 300
+    fallback: fix_loop_gate
+
+  verify_tests:
+    id: verify_tests
+    type: script
+    description: Run the project's test command. Routes to end_success on pass, fix_loop_gate on failure.
+    script: scripts/verify_tests.sh
+    timeout: 600
+    fallback: fix_loop_gate
+
+  fix_loop_gate:
+    id: fix_loop_gate
+    type: script
+    description: Budget gate. Loops back to implement with fix_instructions populated, or terminates as end_failure.
+    script: scripts/fix_loop_gate.sh
+    timeout: 5
+    fallback: end_failure
+
+  end_success:
+    id: end_success
+    type: end
+    output: |
+      CODER_COMPLETE
+      Plan: {{plan_summary}}
+      Files modified: {{files_to_modify}}
+      Files created: {{files_to_create}}
+      Build: passed
+      Tests: passed
+
+  end_rejected:
+    id: end_rejected
+    type: end
+    output: |
+      CODER_REJECTED
+      Plan was rejected at the approval gate.
+      Plan: {{plan_summary}}
+
+  end_failure:
+    id: end_failure
+    type: end
+    output: |
+      CODER_FAILED
+      Plan: {{plan_summary}}
+      Attempts: {{fix_attempts}}/{{max_fix_attempts}}
+
+      Last node output:
+      {{last_node_output}}
+
+      Last build output:
+      {{build_output}}
+
+      Last tests output:
+      {{tests_output}}

assets/agents/coder/scripts/fix_loop_gate.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+fix_attempts=$(echo "$state" | jq -r '.fix_attempts // 0')
+max_fix_attempts=$(echo "$state" | jq -r '.max_fix_attempts // 3')
+build_ok=$(echo "$state" | jq -r '.build_ok | if . == null then "true" else (. | tostring) end')
+tests_ok=$(echo "$state" | jq -r '.tests_ok | if . == null then "true" else (. | tostring) end')
+build_output=$(echo "$state" | jq -r '.build_output // ""')
+tests_output=$(echo "$state" | jq -r '.tests_output // ""')
+
+if (( fix_attempts >= max_fix_attempts )); then
+  jq -nc \
+    --argjson n "$fix_attempts" \
+    '{
+      "fix_attempts": $n,
+      "_next": "end_failure"
+    }'
+  exit 0
+fi
+
+next_attempts=$((fix_attempts + 1))
+
+if [[ "$build_ok" != "true" ]]; then
+  fix_instructions=$(printf '## Fix loop status (attempt %d of %d)\n\nThe previous attempt failed the build.\n\nBuild output:\n```\n%s\n```\n\nIdentify the minimal fix and apply it. Do not refactor.' \
+    "$next_attempts" "$max_fix_attempts" "$build_output")
+elif [[ "$tests_ok" != "true" ]]; then
+  fix_instructions=$(printf '## Fix loop status (attempt %d of %d)\n\nBuild passed but tests failed.\n\nTest output:\n```\n%s\n```\n\nIdentify the minimal fix and apply it. Do not refactor.' \
+    "$next_attempts" "$max_fix_attempts" "$tests_output")
+else
+  fix_instructions=$(printf '## Fix loop status (attempt %d of %d)\n\nfix_loop_gate was reached but no failure was detected in state. Re-run the verification step.' \
+    "$next_attempts" "$max_fix_attempts")
+fi
+
+jq -nc \
+  --argjson n "$next_attempts" \
+  --arg fi "$fix_instructions" \
+  '{
+    "fix_attempts": $n,
+    "fix_instructions": $fi,
+    "_next": "implement"
+  }'

assets/agents/coder/scripts/resolve_paths.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+project_dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+resolved=$(cd "$project_dir" 2>/dev/null && pwd) || resolved="$project_dir"
+
+jq -nc \
+  --arg pd "$resolved" \
+  '{
+    "project_dir": $pd,
+    "_next": "analyze_request"
+  }'

assets/agents/coder/scripts/route_complexity.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+complexity=$(echo "$state" | jq -r '.complexity_score // 0')
+
+if [[ "${CODER_AUTOAPPROVE:-0}" == "1" ]]; then
+  jq -nc '{"_next": "implement"}'
+  exit 0
+fi
+
+if (( complexity >= 7 )); then
+  jq -nc '{"_next": "gate_approval"}'
+else
+  jq -nc '{"_next": "implement"}'
+fi

assets/agents/coder/scripts/verify_build.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# shellcheck disable=SC1091
+source "$(dirname "$0")/../../.shared/utils.sh"
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+project_dir=$(echo "$state" | jq -r '.project_dir // "."')
+
+if [[ -n "${BUILD_CMD:-}" ]]; then
+  cmd="$BUILD_CMD"
+else
+  project_info=$(detect_project "$project_dir")
+  cmd=$(echo "$project_info" | jq -r '.check // .build // ""')
+fi
+
+if [[ -z "$cmd" || "$cmd" == "null" ]]; then
+  jq -nc '{
+    "build_ok": true,
+    "build_output": "(no build/check command available for this project type)",
+    "_next": "verify_tests"
+  }'
+  exit 0
+fi
+
+exit_code=0
+output=$(cd "$project_dir" && eval "$cmd" 2>&1) || exit_code=$?
+
+if (( exit_code == 0 )); then
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    '{
+      "build_ok": true,
+      "build_output": ("Ran: " + $cmd + "\n\n" + $out),
+      "_next": "verify_tests"
+    }'
+else
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    --argjson rc "$exit_code" \
+    '{
+      "build_ok": false,
+      "build_output": ("Ran: " + $cmd + "\nExit code: " + ($rc | tostring) + "\n\n" + $out),
+      "_next": "fix_loop_gate"
+    }'
+fi

assets/agents/coder/scripts/verify_tests.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+# shellcheck disable=SC1091
+source "$(dirname "$0")/../../.shared/utils.sh"
+
+if [[ -n "${GRAPH_STATE_FILE:-}" ]]; then
+  state=$(cat "$GRAPH_STATE_FILE")
+elif [[ -n "${GRAPH_STATE:-}" ]]; then
+  state="$GRAPH_STATE"
+else
+  state='{}'
+fi
+
+project_dir=$(echo "$state" | jq -r '.project_dir // "."')
+
+if [[ -n "${TEST_CMD:-}" ]]; then
+  cmd="$TEST_CMD"
+else
+  project_info=$(detect_project "$project_dir")
+  cmd=$(echo "$project_info" | jq -r '.test // ""')
+fi
+
+if [[ -z "$cmd" || "$cmd" == "null" ]]; then
+  jq -nc '{
+    "tests_ok": true,
+    "tests_output": "(no test command available for this project type)",
+    "_next": "end_success"
+  }'
+  exit 0
+fi
+
+exit_code=0
+output=$(cd "$project_dir" && eval "$cmd" 2>&1) || exit_code=$?
+
+if (( exit_code == 0 )); then
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    '{
+      "tests_ok": true,
+      "tests_output": ("Ran: " + $cmd + "\n\n" + $out),
+      "_next": "end_success"
+    }'
+else
+  jq -nc \
+    --arg out "$output" \
+    --arg cmd "$cmd" \
+    --argjson rc "$exit_code" \
+    '{
+      "tests_ok": false,
+      "tests_output": ("Ran: " + $cmd + "\nExit code: " + ($rc | tostring) + "\n\n" + $out),
+      "_next": "fix_loop_gate"
+    }'
+fi

assets/agents/coder/tools.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Coder agent tools for implementing code changes
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# @cmd Verify the project builds successfully
+verify_build() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+  local build_cmd
+  build_cmd=$(echo "${project_info}" | jq -r '.check // .build')
+  
+  if [[ -z "${build_cmd}" ]] || [[ "${build_cmd}" == "null" ]]; then
+    warn "No build command detected" >> "$LLM_OUTPUT"
+    return 0
+  fi
+  
+  info "Running: ${build_cmd}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local output exit_code=0
+  output=$(cd "${project_dir}" && eval "${build_cmd}" 2>&1) || exit_code=$?
+  
+  echo "${output}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  if [[ ${exit_code} -eq 0 ]]; then
+    green "BUILD SUCCESS" >> "$LLM_OUTPUT"
+    return 0
+  else
+    error "BUILD FAILED (exit code: ${exit_code})" >> "$LLM_OUTPUT"
+    return 1
+  fi
+}
+
+# @cmd Run project tests
+run_tests() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+  local test_cmd
+  test_cmd=$(echo "${project_info}" | jq -r '.test')
+  
+  if [[ -z "${test_cmd}" ]] || [[ "${test_cmd}" == "null" ]]; then
+    warn "No test command detected" >> "$LLM_OUTPUT"
+    return 0
+  fi
+  
+  info "Running: ${test_cmd}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local output exit_code=0
+  output=$(cd "${project_dir}" && eval "${test_cmd}" 2>&1) || exit_code=$?
+  
+  echo "${output}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  if [[ ${exit_code} -eq 0 ]]; then
+    green "TESTS PASSED" >> "$LLM_OUTPUT"
+    return 0
+  else
+    error "TESTS FAILED (exit code: ${exit_code})" >> "$LLM_OUTPUT"
+    return 1
+  fi
+}
+
+# @cmd Get project structure for context
+get_project_structure() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  {
+  	info "Project: $(echo "${project_info}" | jq -r '.type')"
+  	echo ""
+  
+  	get_tree "${project_dir}" 2
+  } >> "$LLM_OUTPUT"
+}
+

assets/agents/deep-research/README.md

@@ -0,0 +1,274 @@
+# deep-research
+
+A deep web research agent, built as a Loki graph agent. It plans an
+investigation, decomposes it into sub-questions researched in
+parallel, grounds the work in a local knowledge corpus, vets the
+credibility of cited sources, runs a reflexion self-critique loop to
+revise weak findings, delegates the final write-up to a focused
+sub-agent, checks that the cited sources are reachable, and gates the
+result behind human approval.
+
+Unlike a regular agent (which takes a goal and improvises the steps),
+this agent runs a fixed graph: every request goes through the same
+`plan -> parallel research -> vet -> critique -> synthesize -> verify -> approve`
+pipeline.
+
+This agent is also the **canonical reference for the Loki graph
+system**: it exercises every node type (`script`, `llm`, `rag`, `map`,
+`agent`, `input`, `approval`, `end`) and both static fan-out and
+dynamic `map` fan-out. If you are learning how to build a graph
+agent, this is the file to read alongside the
+[Graph-Agents wiki](https://github.com/Dark-Alex-17/loki/wiki/Graph-Agents).
+
+## Workflow
+
+17 nodes. `->` is the static route; a script node can also route
+dynamically via `_next`. The `▶▶` line is a parallel super-step —
+those branches run concurrently:
+
+```
+parse_request (script)              -> bootstrap_research   (or -> ask_topic if no topic)
+ask_topic (input)                   -> bootstrap_research
+bootstrap_research (script)         -> [plan, knowledge_lookup]   ▶▶ parallel
+plan (llm + output_schema)          -> research_each_question
+knowledge_lookup (rag)              -> research_each_question
+research_each_question (map)        -> combine_findings    (spawns one branch per question)
+  └─ research_one_question (llm)    (atomic; runs N×, joins at map)
+combine_findings (script)           -> vet_sources
+vet_sources (llm + custom tool)     -> critique
+critique (llm)                      -> reflexion_gate
+reflexion_gate (script)             -> synthesize  (or -> research_each_question: reflexion loop)
+synthesize (agent: report-writer)   -> verify_sources
+verify_sources (script)             -> approve
+approve (approval)                  -> end_accepted          ("accept")
+                                    -> end_rejected          ("reject")
+                                    -> incorporate_feedback   (any free-form answer)
+incorporate_feedback (script)       -> research_each_question (the human-feedback loop)
+```
+
+### Node-type breakdown
+
+| Type | Nodes |
+|---|---|
+| `script` (Python) | `parse_request`, `bootstrap_research`, `combine_findings`, `reflexion_gate`, `verify_sources`, `incorporate_feedback` |
+| `llm` (tools: `[]`) | `plan`, `critique` |
+| `llm` (with tool whitelist) | `research_one_question`, `vet_sources` |
+| `rag` | `knowledge_lookup` — local corpus retrieval |
+| `map` | `research_each_question` — dynamic fan-out per sub-question |
+| `agent` | `synthesize` — spawns the `report-writer` sub-agent |
+| `input` | `ask_topic` |
+| `approval` | `approve` |
+| `end` | `end_accepted`, `end_rejected` |
+
+## Parallel execution
+
+The graph has two parallel super-steps where Loki's BSP scheduler runs
+branches concurrently.
+
+**1. Context loading (`plan` ‖ `knowledge_lookup`)** — after
+`bootstrap_research`, the LLM planner (which decomposes the topic into
+sub-questions) and the RAG retrieval over the local `knowledge/`
+corpus run side by side. They write disjoint state keys (`plan` writes
+`research_plan` and `questions`; `knowledge_lookup` writes
+`local_context` and `local_sources`) so no reducer is needed.
+
+**2. Per-question research (`research_each_question` map)** — the
+plan emits a `questions` array (3-5 entries, enforced by its
+`output_schema`). The `map` node spawns one parallel branch per
+question (`max_concurrency: 3`). Each branch is an isolated
+`research_one_question` LLM invocation with web tools, instructed to
+investigate exactly its assigned question. Outputs collect into
+`question_findings` in input order, then `combine_findings` joins
+them into a single `findings` Markdown document for downstream nodes.
+
+`settings.max_concurrency: 4` is the graph-wide cap; the per-`map`
+override (`max_concurrency: 3` on `research_each_question`) is
+deliberately lower to leave headroom for the planner's tool calls
+running alongside RAG.
+
+## Local knowledge corpus
+
+`knowledge_lookup` is a `rag` node — it runs hybrid (vector + keyword)
+retrieval over every file in `knowledge/`. The directory ships with a
+small `research-style-notes.md` so the RAG node has something to
+retrieve against on a clean install; drop your own Markdown notes,
+PDFs, or text files into `knowledge/` to bias the research toward
+your local context.
+
+The knowledge base is built once, at agent-load time, into
+`~/.config/loki/agents/deep-research/knowledge_lookup.yaml`. Because
+the node fully specifies its build config (`embedding_model`,
+`chunk_size`, `chunk_overlap`), the build is non-interactive. Delete
+that cached file after adding or changing knowledge to force a
+rebuild.
+
+## Sub-agent: report-writer
+
+The `synthesize` node is an `agent` node that spawns the
+`report-writer` sub-agent (`assets/agents/report-writer/`). This is
+the agent-as-tool pattern: the orchestrating graph delegates the
+writing phase to a focused sub-agent dedicated to coherent prose,
+while the research phase uses different (typically cheaper) LLM nodes
+for fast-and-many-question investigation.
+
+The `report-writer` sub-agent has no tools — it cannot access the
+web, cannot search, and cannot invent facts. It reads only the
+findings it is given and produces a final Markdown report preserving
+every inline citation. See `assets/agents/report-writer/README.md`
+for details.
+
+## Tools and tool scoping
+
+This agent demonstrates Loki's three tool sources and how an `llm`
+node's `tools:` whitelist scopes them per node.
+
+The agent's full tool universe, declared in `graph.yaml`:
+
+- **Global tools** (`global_tools`): `web_search_loki`,
+  `fetch_url_via_curl`, `search_arxiv` - Loki's built-in tool scripts.
+- **MCP server** (`mcp_servers`): `ddg-search` - a DuckDuckGo web
+  search MCP server. Referenced in a whitelist as `mcp:ddg-search`.
+- **Custom agent tool** (`tools.sh`): `classify_source` - a
+  deterministic source-credibility classifier shipped with this agent.
+
+No node receives all of these. Each `llm` node's `tools:` whitelist
+narrows the universe to exactly what that step needs:
+
+| Node | `tools:` whitelist | Draws from |
+|---|---|---|
+| `plan`, `critique` | `[]` | nothing - pure reasoning |
+| `research_one_question` | `web_search_loki`, `fetch_url_via_curl`, `search_arxiv`, `mcp:ddg-search` | global tools + MCP |
+| `vet_sources` | `classify_source` | the custom tool only |
+
+`research_one_question` (each parallel branch of the map) can search
+and fetch but cannot classify sources; `vet_sources` can classify
+sources but cannot touch the web. That separation is the point of the
+`tools:` whitelist: a node gets only the tools its job calls for,
+never the agent's full set.
+
+The `classify_source` custom tool (`tools.sh`) takes a URL and returns
+a credibility tier (government, academic, preprint, organization,
+unverified) derived from the host and top-level domain. It is
+deterministic - exactly the kind of logic a tool should own rather than
+the LLM guessing.
+
+Web search may require API-key configuration; see the
+[Tools](https://github.com/Dark-Alex-17/loki/wiki/Tools) docs.
+`fetch_url_via_curl`, `search_arxiv`, and `classify_source` work
+without a key.
+
+## Setup
+
+`research_one_question` (each parallel branch of the `map`) uses the
+`ddg-search` MCP server via `mcp:ddg-search`. It is one of Loki's
+default MCP servers; make sure it is registered in
+`~/.config/loki/mcp.json` (run `loki --install mcp_config` to restore
+the default template if it is missing). If `ddg-search` is unavailable,
+the branches still have their global web-search tools to fall back on.
+
+The `synthesize` node spawns the `report-writer` sub-agent. Both
+agents ship with `loki agents install`; if you install one manually,
+install both so the agent reference resolves.
+
+## Reflexion
+
+The agent has two loops, both built with script nodes that route via
+`_next`. The engine allows back-edges at runtime; the validator only
+rejects cycles built from static `next` / `routes` edges, so script
+`_next` loops are always allowed.
+
+**Automated reflexion loop.** After the parallel research map and
+`vet_sources`, the `critique` node reviews the merged findings
+against the research plan and the source credibility assessment, and
+emits `VERDICT: PASS` or `VERDICT: REVISE` with specific feedback.
+`reflexion_gate.py` then:
+
+- `PASS` -> continue to `synthesize`.
+- `REVISE`, budget remaining -> loop back to `research_each_question`,
+  with the critique injected as `research_feedback` so every parallel
+  branch sees it on the retry.
+- `REVISE`, budget spent -> continue to `synthesize` anyway (the human
+  approval step is the final backstop).
+
+The budget is `MAX_REFLEXION_REVISIONS` in `reflexion_gate.py`
+(default 2, so the research map runs at most 3 times per pass).
+
+**Human-feedback loop.** At `approve` the user answers `accept`,
+`reject`, or types their own feedback. A free-form answer routes via
+the approval node's `on_other` to `incorporate_feedback.py`, which
+folds that text into `research_feedback` and loops back to
+`research_each_question` for another parallel pass.
+
+`settings.max_loop_iterations` (40) is the engine's infinite-loop
+backstop: it caps the total visits to any single node.
+
+## Running
+
+```sh
+loki agents install                  # ships deep-research
+loki -a deep-research "How does HTTP/3 differ from HTTP/2?"
+loki -a deep-research "Recent advances in solid-state batteries"
+loki -a deep-research                # no prompt -> triggers ask_topic
+```
+
+## Anti-hallucination
+
+- `research_one_question` (each map branch) is instructed to back
+  every claim with a real retrieved source and never to fabricate
+  URLs, titles, or DOIs.
+- `vet_sources` classifies every cited source so weak sources are
+  visible to the critique step.
+- `critique` independently reviews the merged findings and sends weak
+  or uncited work back for another parallel research pass.
+- `synthesize` (the `report-writer` sub-agent) is grounded: it may use
+  only the gathered findings and must keep each claim's inline source.
+  It has no tools and cannot browse the web.
+- `verify_sources` probes every cited URL / DOI with an HTTP HEAD
+  request and reports which are unreachable, so the human reviewer
+  sees broken citations before approving.
+
+## Customizing
+
+- **Loop budget.** `MAX_REFLEXION_REVISIONS` in `reflexion_gate.py`.
+- **Map concurrency.** The `research_each_question` node's
+  `max_concurrency: 3` caps simultaneous web-research branches.
+  Raise to investigate more questions in parallel; lower to be gentle
+  on rate-limited providers.
+- **Per-node model.** Add `model: anthropic:...` to any `llm` node.
+  Cheap models work well for `plan` / `critique` / `vet_sources`; the
+  heavy intelligence is needed in `research_one_question` and the
+  `report-writer` sub-agent.
+- **Tool scope.** Narrow the `research_one_question` node's `tools:`
+  list to constrain where each branch looks (for example, drop
+  `web_search_loki` and `mcp:ddg-search` to force arXiv-only
+  research).
+- **Local knowledge.** Drop files into `knowledge/` to bias every
+  research branch toward your local context (see the *Local
+  knowledge corpus* section above).
+- **Different writer.** Replace `agent: report-writer` on the
+  `synthesize` node with the name of any other agent. The
+  orchestrator does not care what kind of agent the writer is.
+- **Skip approval.** Point both `approve` routes at `end_accepted`,
+  or wire `verify_sources` straight to an `end` node.
+
+## Files
+
+```
+assets/agents/deep-research/
+  graph.yaml                    - agent config + 17-node workflow
+  tools.sh                      - classify_source custom tool
+  README.md                     - this file
+  knowledge/
+    README.md                   - corpus-format notes
+    research-style-notes.md     - starter knowledge file (replace with your notes)
+  scripts/
+    parse_request.py            - _next: bootstrap_research, or ask_topic if no topic
+    bootstrap_research.py       - fan-out source: next [plan, knowledge_lookup]
+    combine_findings.py         - joins map output (question_findings) into findings
+    reflexion_gate.py           - _next: research_each_question (revise) or synthesize
+    verify_sources.py           - HTTP HEAD on cited URLs / DOIs
+    incorporate_feedback.py     - _next: research_each_question, with user feedback
+```
+
+See also `assets/agents/report-writer/` — the sub-agent the
+`synthesize` node spawns.

assets/agents/deep-research/graph.yaml

@@ -0,0 +1,293 @@
+name: deep-research
+description: |
+  Deep web research workflow. Plans an investigation, decomposes it
+  into sub-questions researched in parallel, grounds the work in a
+  local knowledge corpus, vets the credibility of cited sources, runs
+  a reflexion self-critique loop to revise weak or incomplete findings,
+  delegates the final write-up to a focused sub-agent, checks that the
+  cited sources are reachable, and gates the result behind human
+  approval. A reviewer's free-form feedback at the approval step feeds
+  back into another research pass.
+
+  This is the canonical Loki graph-agent reference: it exercises every
+  node type (script, llm, rag, map, agent, input, approval, end) and
+  both static fan-out and dynamic map fan-out.
+
+version: "1.0"
+
+temperature: 0.0
+
+global_tools:
+  - web_search_loki.sh
+  - fetch_url_via_curl.sh
+  - search_arxiv.sh
+
+mcp_servers:
+  - ddg-search
+
+conversation_starters:
+  - "How does HTTP/3 differ from HTTP/2?"
+  - "Summarize recent advances in solid-state battery chemistry"
+
+settings:
+  max_loop_iterations: 40
+  log_state_snapshots: false
+  validate_before_run: true
+  max_concurrency: 4
+
+initial_state:
+  research_feedback: ""
+  research_attempts: 0
+  local_context: ""
+  local_sources: ""
+
+start: parse_request
+
+nodes:
+
+  parse_request:
+    id: parse_request
+    type: script
+    script: scripts/parse_request.py
+    next: bootstrap_research
+
+  ask_topic:
+    id: ask_topic
+    type: input
+    question: "What would you like me to research?"
+    validation: "len(input) > 0"
+    state_updates:
+      topic: "{{input}}"
+    next: bootstrap_research
+
+  bootstrap_research:
+    id: bootstrap_research
+    type: script
+    script: scripts/bootstrap_research.py
+    next: [plan, knowledge_lookup]
+
+  plan:
+    id: plan
+    type: llm
+    instructions: |
+      You are a research planner. Given a topic, produce a focused
+      research plan and decompose it into 3-5 specific sub-questions
+      that can each be researched independently in parallel.
+
+      The plan is a short narrative naming the key questions and the
+      kinds of sources that would be authoritative. The sub-questions
+      are precise, self-contained queries (each one is sent on its own
+      to a separate research worker, so they must be answerable
+      without each other's context).
+    prompt: "Research topic: {{topic}}"
+    tools: []
+    output_schema:
+      type: object
+      properties:
+        research_plan:
+          type: string
+          description: A short plan narrative.
+        questions:
+          type: array
+          items: { type: string }
+          minItems: 1
+          maxItems: 6
+          description: 3-5 specific, self-contained sub-questions.
+      required: [research_plan, questions]
+    next: research_each_question
+
+  knowledge_lookup:
+    id: knowledge_lookup
+    type: rag
+    documents:
+      - ./knowledge/
+    query: "{{topic}}"
+    top_k: 6
+    chunk_size: 1000
+    chunk_overlap: 100
+    state_updates:
+      local_context: "{{output.context}}"
+      local_sources: "{{output.sources}}"
+    next: research_each_question
+
+  research_each_question:
+    id: research_each_question
+    type: map
+    over: "{{questions}}"
+    as: question
+    branch: research_one_question
+    collect_into: question_findings
+    max_concurrency: 3
+    next: combine_findings
+
+  research_one_question:
+    id: research_one_question
+    type: llm
+    instructions: |
+      You are a web research assistant. Investigate the SINGLE question
+      given to you using your tools: search the web, fetch and read
+      pages, and search arXiv for academic sources.
+
+      Rules:
+        - Every factual claim must be backed by a real source you
+          actually retrieved. Never fabricate URLs, page titles,
+          authors, or DOIs.
+        - Prefer primary and authoritative sources over aggregators.
+        - Where sources disagree, report the disagreement rather than
+          papering over it.
+        - Put the URL (or DOI) inline next to each claim it supports.
+
+      Return organized findings in plain text. Do not include
+      meta-commentary about the process.
+    prompt: |
+      Research question: {{question}}
+
+      Local context that may help:
+      {{local_context}}
+
+      {{research_feedback}}
+    tools:
+      - web_search_loki
+      - fetch_url_via_curl
+      - search_arxiv
+      - mcp:ddg-search
+    max_iterations: 10
+    max_attempts: 2
+    temperature: 0.1
+
+  combine_findings:
+    id: combine_findings
+    type: script
+    script: scripts/combine_findings.py
+    next: vet_sources
+
+  vet_sources:
+    id: vet_sources
+    type: llm
+    instructions: |
+      You assess the credibility of the sources cited in a set of
+      research findings. For every distinct source URL in the findings,
+      call the `classify_source` tool to get its credibility tier. Then
+      summarize: which claims rest on HIGH-credibility sources, and
+      which rest on PREPRINT or UNVERIFIED sources and so need
+      corroboration. Do NOT do any new research -- assess only what is
+      already cited.
+    prompt: |
+      Findings to assess:
+      {{findings}}
+    tools:
+      - classify_source
+    max_iterations: 15
+    state_updates:
+      source_assessment: "{{output}}"
+    next: critique
+
+  critique:
+    id: critique
+    type: llm
+    instructions: |
+      You are a meticulous research reviewer. Judge whether the
+      findings below are good enough to synthesize a complete,
+      well-supported report that answers the research plan.
+
+      Mark the findings REVISE if ANY of these hold:
+        - A research-plan question is unanswered or only weakly
+          addressed.
+        - A factual claim has no source, or cites a source that looks
+          fabricated.
+        - The findings lean on a single source where corroboration is
+          needed.
+        - A key claim rests only on a PREPRINT or UNVERIFIED source,
+          per the source credibility assessment below.
+        - An obvious counter-perspective or recent development is
+          missing.
+      Otherwise mark them PASS.
+
+      Respond in EXACTLY this format, nothing else:
+
+      VERDICT: <PASS or REVISE>
+      FEEDBACK: <if REVISE, be specific and actionable -- name the gaps
+      and what kind of source would close them; if PASS, write "none">
+    prompt: |
+      Research plan:
+      {{research_plan}}
+
+      Findings under review:
+      {{findings}}
+
+      Source credibility assessment:
+      {{source_assessment}}
+    tools: []
+    state_updates:
+      critique: "{{output}}"
+    next: reflexion_gate
+
+  reflexion_gate:
+    id: reflexion_gate
+    type: script
+    script: scripts/reflexion_gate.py
+    next: synthesize
+
+  synthesize:
+    id: synthesize
+    type: agent
+    agent: report-writer
+    prompt: |
+      Research topic: {{topic}}
+
+      Findings (organized by sub-question, with inline citations):
+      {{findings}}
+
+      Source credibility assessment:
+      {{source_assessment}}
+
+      Produce the final report following your instructions.
+    timeout: 300
+    state_updates:
+      report: "{{output}}"
+    next: verify_sources
+
+  verify_sources:
+    id: verify_sources
+    type: script
+    script: scripts/verify_sources.py
+    next: approve
+
+  approve:
+    id: approve
+    type: approval
+    question: |
+      Research report on: {{topic}}
+
+      {{report}}
+
+      ----
+      {{source_check}}
+      ----
+
+      Accept this report? Pick "accept" or "reject", or type specific
+      feedback to send the research back for another pass.
+    options:
+      - "accept"
+      - "reject"
+    routes:
+      "accept": end_accepted
+      "reject": end_rejected
+    on_other: incorporate_feedback
+    state_updates:
+      decision: "{{choice}}"
+
+  incorporate_feedback:
+    id: incorporate_feedback
+    type: script
+    script: scripts/incorporate_feedback.py
+
+  end_accepted:
+    id: end_accepted
+    type: end
+    output: "{{report}}"
+
+  end_rejected:
+    id: end_rejected
+    type: end
+    output: "Research on '{{topic}}' was rejected and discarded."

assets/agents/deep-research/knowledge/README.md

@@ -0,0 +1,23 @@
+# Local knowledge corpus for deep-research
+
+The `knowledge_lookup` node in `graph.yaml` is a `rag` node that runs
+hybrid (vector + keyword) retrieval over every file in this directory.
+Drop your own notes, papers (PDFs), Markdown docs, or text files here
+and they will be indexed into a per-agent knowledge base on first run.
+
+Loki supports common file types out of the box: `.md`, `.txt`, `.pdf`,
+`.html`, and others. Subdirectories are walked recursively.
+
+A small starter file (`research-style-notes.md`) ships so the RAG
+node has something non-empty to retrieve against on a clean install.
+Replace or extend it with your own materials to bias the research
+phase toward your local context.
+
+To force the knowledge base to rebuild after you add or change files,
+delete the cached index:
+
+```sh
+rm ~/.config/loki/agents/deep-research/knowledge_lookup.yaml
+```
+
+The next run will rebuild from the current contents of this directory.

assets/agents/deep-research/knowledge/research-style-notes.md

@@ -0,0 +1,49 @@
+# Research style notes
+
+These are general principles the `deep-research` agent should keep in
+mind regardless of topic. Replace this file with your own notes if you
+want to bias retrieval toward your local context.
+
+## What "good research" means here
+
+- **Every factual claim cites a source you actually retrieved.** Never
+  fabricate URLs, page titles, authors, or DOIs.
+- **Primary sources beat aggregators.** Prefer the original paper, the
+  RFC, the standards body, or the manufacturer over a blog summarizing
+  them.
+- **Corroboration matters where stakes are high.** If a single source
+  makes a strong claim, look for a second independent source before
+  taking it as established.
+- **Disagreement is information, not noise.** If two credible sources
+  disagree, report the disagreement and the reasoning on each side.
+- **Old does not mean wrong.** A 2014 RFC is still authoritative if no
+  newer one has obsoleted it; check before assuming a source is stale.
+
+## Source-tier heuristics
+
+The `vet_sources` node uses these rough tiers to weigh credibility.
+The custom tool `classify_source` (see `tools.sh`) implements this
+deterministically by hostname / TLD.
+
+- **HIGH:** government domains (`.gov`, `.mil`), academic institutions
+  (`.edu`, university subdomains), peer-reviewed journals, standards
+  bodies (IETF/RFCs, W3C, ISO, IEEE, NIST), and primary documents from
+  the entities being researched (e.g. a vendor's official spec page).
+- **PREPRINT:** arXiv, bioRxiv, medRxiv, SSRN. Useful but not yet
+  peer-reviewed; treat numeric claims with extra caution.
+- **ORGANIZATION:** established nonprofits, standards-adjacent groups,
+  industry consortia. Reliable for their stated mission but may have a
+  perspective.
+- **UNVERIFIED:** general web pages, blogs, news aggregators, social
+  media. Useful for leads but should not be the only source for a
+  factual claim.
+
+## Common pitfalls to flag in critique
+
+- A claim cited only to a PREPRINT or UNVERIFIED source on a numeric
+  or contested point.
+- A research-plan question that the findings address only obliquely.
+- "Findings" that paraphrase a single source three times rather than
+  triangulating.
+- Citation collisions where two sources are listed but turn out to
+  be the same study reported via different aggregators.

assets/agents/deep-research/scripts/bootstrap_research.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""Fan-out source for context loading.
+
+Has no logic of its own. Exists so the static `next: [plan, knowledge_lookup]`
+list on this node fans out into two parallel branches (the LLM planner and
+the RAG knowledge lookup) as a single super-step. The validator requires
+declared parallel-branch script outputs, so we emit an empty JSON object
+explicitly here.
+"""
+import json
+
+
+def main():
+    print(json.dumps({}))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/scripts/combine_findings.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Join the per-question map outputs into a single `findings` string.
+
+The `research_each_question` map writes `question_findings` (an array,
+one entry per sub-question, in input order). Downstream nodes
+(`vet_sources`, `critique`, `synthesize`) read `{{findings}}` as a
+single block, so this script renders the array as a Markdown document
+with one section per question.
+"""
+import json
+import os
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def main():
+    state = load_state()
+    questions = state.get("questions") or []
+    per_question = state.get("question_findings") or []
+
+    sections = []
+    for idx, q in enumerate(questions):
+        body = per_question[idx] if idx < len(per_question) else ""
+        if isinstance(body, dict) or isinstance(body, list):
+            body = json.dumps(body, indent=2)
+        sections.append(f"## {q}\n\n{body}")
+
+    findings = "\n\n".join(sections) if sections else "No findings gathered."
+    print(json.dumps({"findings": findings}))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/scripts/incorporate_feedback.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Fold a reviewer's free-form feedback back into the research loop.
+
+Runs when the user answers the approval step with their own text
+instead of "accept" or "reject". That text (saved by the approval node
+as `decision`) becomes `research_feedback`, and the graph loops back to
+`research_each_question` for another informed pass (each sub-question is
+re-researched in parallel with the new feedback in context). The
+reflexion counter is reset so the user-driven pass gets a fresh revision
+budget.
+
+Routing (`_next`): always research_each_question.
+"""
+import json
+import os
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def main():
+    state = load_state()
+    feedback = (state.get("decision") or "").strip()
+    output = {
+        "_next": "research_each_question",
+        "research_attempts": 0,
+        "research_feedback": (
+            "The user reviewed the report and asked for changes. Treat "
+            "this as the top priority for the next pass:\n\n" + feedback
+        ),
+    }
+    print(json.dumps(output))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/scripts/parse_request.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+"""Entry router for deep-research.
+
+Reads the caller's prompt from state. If it contains a usable research
+topic, stores it as `topic` and falls through to the static `next`
+(plan). If the prompt is empty, routes to `ask_topic` so the user can
+supply one interactively.
+
+Routing (`_next`):
+  - prompt present -> (no _next; static next: plan)
+  - prompt empty   -> ask_topic
+"""
+import json
+import os
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def main():
+    state = load_state()
+    prompt = (state.get("initial_prompt") or "").strip()
+    if prompt:
+        print(json.dumps({"topic": prompt}))
+    else:
+        print(json.dumps({"_next": "ask_topic"}))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/scripts/reflexion_gate.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""Reflexion gate for deep-research.
+
+Runs after `critique` has reviewed the current research findings. If the
+critique's verdict is REVISE and the reflexion budget is not spent,
+loops back to `research` with the critique attached as
+`research_feedback`, so the retry is informed rather than a blind
+re-run. Otherwise it proceeds to `synthesize`.
+
+Routing (`_next`):
+  - verdict PASS                     -> synthesize
+  - verdict REVISE, budget remaining -> research_each_question  (+ research_feedback)
+  - verdict REVISE, budget spent     -> synthesize
+
+Reflexion is a best-effort quality booster, not a hard gate: once the
+budget is spent the workflow proceeds anyway, and the human approval
+step is the final backstop.
+"""
+import json
+import os
+import re
+
+# Automated revision passes allowed. `research` runs at most
+# MAX_REFLEXION_REVISIONS + 1 times per user pass. Bump to allow more.
+MAX_REFLEXION_REVISIONS = 2
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def as_int(value, default=0):
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def parse_verdict(critique):
+    """Pull PASS/REVISE from the critique's `VERDICT:` line. Defaults to
+    PASS when no verdict line is found, so a malformed critique lets the
+    workflow proceed instead of burning the whole revision budget."""
+    match = re.search(r"VERDICT:\s*([A-Za-z]+)", critique, re.IGNORECASE)
+    if not match:
+        return "PASS"
+    return match.group(1).upper()
+
+
+def main():
+    state = load_state()
+    critique = state.get("critique") or ""
+    verdict = parse_verdict(critique)
+    attempts = as_int(state.get("research_attempts"))
+
+    if verdict == "REVISE" and attempts < MAX_REFLEXION_REVISIONS:
+        feedback = (
+            "A reviewer judged the previous research pass incomplete. "
+            "Address every point in the critique below:\n\n" + critique
+        )
+        output = {
+            "_next": "research_each_question",
+            "research_attempts": attempts + 1,
+            "research_feedback": feedback,
+        }
+    else:
+        output = {"_next": "synthesize"}
+
+    print(json.dumps(output))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/scripts/verify_sources.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Check that the sources cited in the research report are reachable.
+
+Scans the final report for URLs and DOIs, probes each with a HEAD
+request, and writes a `source_check` summary into state so the human
+reviewer sees broken citations at the approval step.
+
+Times out per request so a slow source cannot stall the graph.
+"""
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+
+DOI_RE = re.compile(r"\b(10\.\d{4,9}/[-._;()/:A-Z0-9]+)", re.IGNORECASE)
+URL_RE = re.compile(r"https?://[^\s)\]\}\"'>]+")
+
+
+def load_state():
+    path = os.environ.get("GRAPH_STATE_FILE")
+    if path:
+        with open(path) as f:
+            return json.load(f)
+    return json.loads(os.environ.get("GRAPH_STATE", "{}"))
+
+
+def reachable(url, timeout=5.0):
+    req = urllib.request.Request(url, method="HEAD")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return 200 <= resp.status < 400
+    except urllib.error.HTTPError as e:
+        return 200 <= e.code < 400
+    except Exception:
+        return False
+
+
+def main():
+    state = load_state()
+    report = state.get("report") or ""
+
+    urls = sorted({u.rstrip(".,;)") for u in URL_RE.findall(report)})
+    dois = sorted(set(DOI_RE.findall(report)))
+
+    results = []
+    for url in urls:
+        ok = reachable(url)
+        results.append(f"  {'OK' if ok else 'UNREACHABLE'}  {url}")
+    for doi in dois:
+        url = f"https://doi.org/{doi}"
+        if url in urls:
+            continue
+        ok = reachable(url)
+        results.append(f"  {'OK' if ok else 'UNREACHABLE'}  DOI {doi} ({url})")
+
+    if not results:
+        summary = "No web sources were cited in the report."
+    else:
+        summary = (
+            f"Source reachability ({len(results)} checked):\n"
+            + "\n".join(results)
+        )
+
+    print(json.dumps({"source_check": summary}))
+
+
+if __name__ == "__main__":
+    main()

assets/agents/deep-research/tools.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+set -e
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# @cmd Classify the credibility tier of a web source from its URL.
+# A deterministic check based on the host and top-level domain. Use it
+# to weigh how much trust to place in a source before relying on it.
+# @option --url!  The full source URL to classify
+classify_source() {
+    # shellcheck disable=SC2154
+    local url="$argc_url"
+    local host="${url#*://}"
+    host="${host%%/*}"
+    host="${host##*@}"
+    host="${host%%:*}"
+    host="$(printf '%s' "$host" | tr '[:upper:]' '[:lower:]')"
+
+    local tier
+    case "$host" in
+        '')
+            tier="UNKNOWN - no host could be parsed from the URL" ;;
+        *.gov | *.gov.* | *.mil)
+            tier="HIGH - government source" ;;
+        *.edu | *.edu.* | *.ac.*)
+            tier="HIGH - academic institution" ;;
+        arxiv.org | *.arxiv.org | biorxiv.org | *.biorxiv.org | medrxiv.org | *.medrxiv.org | ssrn.com | *.ssrn.com)
+            tier="PREPRINT - not yet peer reviewed, corroborate before citing" ;;
+        wikipedia.org | *.wikipedia.org)
+            tier="TERTIARY - encyclopedia, good for orientation not citation" ;;
+        *.org | *.org.*)
+            tier="MEDIUM - organization site, check for institutional bias" ;;
+        *)
+            tier="UNVERIFIED - general web source, corroborate before citing" ;;
+    esac
+
+    printf '%s: %s\n' "${host:-<none>}" "$tier" >> "$LLM_OUTPUT"
+}

assets/agents/demo/README.md

@@ -0,0 +1,7 @@
+# Demo
+
+This agent serves as a demo to guide agent development and showcase various agent capabilities.
+
+To enable tools, Loki will look for the first `tools.py` or `tools.sh` file it finds in this directory.
+
+The base configuration using `tools.py`. To switch to using `tools.sh`, rename or remove `tools.py`.

assets/agents/demo/config.yaml

@@ -0,0 +1,36 @@
+name: Demo
+description: An AI agent that demonstrates agent capabilities
+version: 0.1.0
+global_tools:
+  - execute_command.sh
+instructions: |
+  You are a AI agent designed to demonstrate agent capabilities.
+
+  <tools>
+  {{__tools__}}
+  </tools>
+
+  <system>
+  os: {{__os__}}
+  os_family: {{__os_family__}}
+  arch: {{__arch__}}
+  shell: {{__shell__}}
+  locale: {{__locale__}}
+  now: {{__now__}}
+  cwd: {{__cwd__}}
+  </system>
+
+  <user>
+  username: {{username}}
+  </user>
+variables:
+  - name: username
+    description: Your user name
+conversation_starters:
+  - What is my username?
+  - What is my current shell?
+  - What is my ip?
+  - How much disk space is left on my PC??
+  - How to create an agent?
+documents:
+  - README.md

assets/agents/demo/tools.py

@@ -0,0 +1,9 @@
+import urllib.request
+
+def get_ipinfo():
+  """
+  Get the ip info
+  """
+  with urllib.request.urlopen("https://httpbin.org/ip") as response:
+    data = response.read()
+    return data.decode('utf-8')

assets/agents/demo/tools.sh.bak

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -e
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# @cmd Get the ip info
+get_ipinfo() {
+    curl -fsSL https://httpbin.org/ip >> "$LLM_OUTPUT"
+}
+

assets/agents/explore/README.md

@@ -0,0 +1,37 @@
+# Explore
+
+An AI agent specialized in exploring codebases, finding patterns, and understanding project structures.
+
+This agent is designed to be delegated to by the **[Sisyphus](../sisyphus/README.md)** agent to gather information and context. Sisyphus
+acts as the coordinator/architect, while Explore handles the research and discovery phase.
+
+It can also be used as a standalone tool for understanding codebases and finding specific information.
+
+## Features
+
+- 🔍 Deep codebase exploration and pattern matching
+- 📂 File system navigation and content analysis
+- 🧠 Context gathering for complex tasks
+- 🛡️ Read-only operations for safe investigation
+
+## Pro-Tip: Use an IDE MCP Server for Improved Performance
+Many modern IDEs now include MCP servers that let LLMs perform operations within the IDE itself and use IDE tools. Using
+an IDE's MCP server dramatically improves the performance of coding agents. So if you have an IDE, try adding that MCP
+server to your config (see the [MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md) to see how to configure
+them), and modify the agent definition to look like this:
+
+```yaml
+# ...
+
+mcp_servers:
+  - jetbrains # The name of your configured IDE MCP server
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - web_search_loki.sh
+
+# ...
+```

assets/agents/explore/config.yaml

@@ -0,0 +1,78 @@
+name: explore
+description: Fast codebase exploration agent - finds patterns, structures, and relevant files
+version: 1.0.0
+temperature: 0.1
+
+variables:
+  - name: project_dir
+    description: Project directory to explore
+    default: '.'
+
+mcp_servers:
+  - ddg-search
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+
+instructions: |
+  You are a codebase explorer. Your job: Search, find, report. Nothing else.
+  
+  ## Your Mission
+  
+  Given a search task, you:
+  1. Search for relevant files and patterns
+  2. Read key files to understand structure
+  3. Report findings concisely
+  4. Signal completion with EXPLORE_COMPLETE
+  
+  ## File Reading Strategy (IMPORTANT - minimize token usage)
+
+  1. **Find first, read second** - Never read a file without knowing why
+  2. **Use grep to locate** - `fs_grep --pattern "struct User" --include "*.rs"` finds exactly where things are
+  3. **Use glob to discover** - `fs_glob --pattern "*.rs" --path src/` finds files by name
+  4. **Read targeted sections** - `fs_read --path "src/main.rs" --offset 50 --limit 30` reads only lines 50-79
+  5. **Never read entire large files** - If a file is 500+ lines, read the relevant section only
+
+  ## Available Actions
+
+  - `fs_grep --pattern "struct User" --include "*.rs"` - Find content across files
+  - `fs_glob --pattern "*.rs" --path src/` - Find files by name pattern
+  - `fs_read --path "src/main.rs"` - Read a file (with line numbers)
+  - `fs_read --path "src/main.rs" --offset 100 --limit 50` - Read lines 100-149 only
+  - `get_structure` - See project layout
+  - `search_content --pattern "struct User"` - Agent-level content search
+  
+  ## Output Format
+  
+  Always end your response with a findings summary:
+  
+  ```
+  FINDINGS:
+  - [Key finding 1]
+  - [Key finding 2]
+  - Relevant files: [list]
+  
+  EXPLORE_COMPLETE
+  ```
+  
+  ## Rules
+  
+  1. **Be fast** - Don't read every file, read representative ones
+  2. **Be focused** - Answer the specific question asked
+  3. **Be concise** - Report findings, not your process
+  4. **Never modify files** - You are read-only
+  5. **Limit reads** - Max 5 file reads per exploration
+  
+  ## Context
+  - Project: {{project_dir}}
+  - CWD: {{__cwd__}}
+  
+  ## Available Tools:
+  {{__tools__}}
+
+conversation_starters:
+  - 'Find how authentication is implemented'
+  - 'What patterns are used for API endpoints'
+  - 'Show me the project structure'

assets/agents/explore/tools.sh

@@ -0,0 +1,175 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Explore agent tools for codebase search and analysis
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# Normalize a path to be relative to project root.
+# Strips the project_dir prefix if the LLM passes an absolute path.
+_normalize_path() {
+  local input_path="$1"
+  local project_dir
+  project_dir=$(_project_dir)
+
+  if [[ "${input_path}" == /* ]]; then
+    input_path="${input_path#"${project_dir}"/}"
+  fi
+
+  input_path="${input_path#./}"
+  echo "${input_path}"
+}
+
+# @cmd Get project structure and layout
+get_structure() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  info "Project structure:" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  {
+  	echo "Type: $(echo "${project_info}" | jq -r '.type')"
+  	echo ""
+
+  	get_tree "${project_dir}" 3
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Search for files by name pattern
+# @option --pattern! File name pattern (e.g., "*.rs", "config*", "*test*")
+search_files() {
+	# shellcheck disable=SC2154
+  local pattern="${argc_pattern}"
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  info "Files matching: ${pattern}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local results
+  results=$(_search_files "${pattern}" "${project_dir}")
+  
+  if [[ -n "${results}" ]]; then
+    echo "${results}" >> "$LLM_OUTPUT"
+  else
+    warn "No files found" >> "$LLM_OUTPUT"
+  fi
+}
+
+# @cmd Search for content in files
+# @option --pattern! Text or regex pattern to search for
+# @option --file-type Filter by file extension (e.g., "rs", "py", "ts")
+search_content() {
+  local pattern="${argc_pattern}"
+  local file_type="${argc_file_type:-}"
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  info "Searching: ${pattern}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local include_arg=""
+  if [[ -n "${file_type}" ]]; then
+    include_arg="--include=*.${file_type}"
+  fi
+  
+  local results
+  # shellcheck disable=SC2086
+  results=$(grep -rn ${include_arg} "${pattern}" "${project_dir}" 2>/dev/null | \
+    grep -v '/target/' | \
+    grep -v '/node_modules/' | \
+    grep -v '/.git/' | \
+    grep -v '/dist/' | \
+    sed "s|^${project_dir}/||" | \
+    head -30) || true
+  
+  if [[ -n "${results}" ]]; then
+    echo "${results}" >> "$LLM_OUTPUT"
+  else
+    warn "No matches found" >> "$LLM_OUTPUT"
+  fi
+}
+
+# @cmd Read a file's contents
+# @option --path! Path to the file (relative to project root)
+# @option --lines Maximum lines to read (default: 200)
+read_file() {
+  local file_path
+	# shellcheck disable=SC2154
+  file_path=$(_normalize_path "${argc_path}")
+  local max_lines="${argc_lines:-200}"
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local full_path="${project_dir}/${file_path}"
+  
+  if [[ ! -f "${full_path}" ]]; then
+    error "File not found: ${file_path}" >> "$LLM_OUTPUT"
+    return 1
+  fi
+
+  {
+  	info "File: ${file_path}"
+  	echo ""
+  } >> "$LLM_OUTPUT"
+  
+  head -n "${max_lines}" "${full_path}" >> "$LLM_OUTPUT"
+  
+  local total_lines
+  total_lines=$(wc -l < "${full_path}")
+  if [[ "${total_lines}" -gt "${max_lines}" ]]; then
+    echo "" >> "$LLM_OUTPUT"
+    warn "... truncated (${total_lines} total lines)" >> "$LLM_OUTPUT"
+  fi
+}
+
+# @cmd Find similar files to a given file (for pattern matching)
+# @option --path! Path to the reference file
+find_similar() {
+  local file_path
+  file_path=$(_normalize_path "${argc_path}")
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local ext="${file_path##*.}"
+  local dir
+  dir=$(dirname "${file_path}")
+  
+  info "Files similar to: ${file_path}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local results
+  results=$(find "${project_dir}/${dir}" -maxdepth 1 -type f -name "*.${ext}" \
+    ! -name "$(basename "${file_path}")" \
+    ! -name "*test*" \
+    ! -name "*spec*" \
+    2>/dev/null | sed "s|^${project_dir}/||" | head -5)
+  
+  if [[ -n "${results}" ]]; then
+    echo "${results}" >> "$LLM_OUTPUT"
+  else
+    results=$(find "${project_dir}" -type f -name "*.${ext}" \
+      ! -name "$(basename "${file_path}")" \
+      ! -name "*test*" \
+      -not -path '*/target/*' \
+      2>/dev/null | sed "s|^${project_dir}/||" | head -5)
+    if [[ -n "${results}" ]]; then
+      echo "${results}" >> "$LLM_OUTPUT"
+    else
+      warn "No similar files found" >> "$LLM_OUTPUT"
+    fi
+  fi
+}

assets/agents/file-reviewer/README.md

@@ -0,0 +1,35 @@
+# File Reviewer
+
+A specialized worker agent that reviews a single file's diff for bugs, style issues, and cross-cutting concerns.
+
+This agent is designed to be spawned by the **[Code Reviewer](../code-reviewer/README.md)** agent. It focuses deeply on 
+one file while communicating with sibling agents to catch issues that span multiple files.
+
+## Features
+
+- 🔍 **Deep Analysis**: Focuses on bugs, logic errors, security issues, and style problems in a single file.
+- 🗣️ **Teammate Communication**: Sends and receives alerts to/from sibling reviewers about interface or dependency 
+  changes.
+- 🎯 **Targeted Reading**: Reads only relevant context around changed lines to stay efficient.
+- 🏷️ **Structured Findings**: Categorizes issues by severity (🔴 Critical, 🟡 Warning, 🟢 Suggestion, 💡 Nitpick).
+
+## Pro-Tip: Use an IDE MCP Server for Improved Performance
+Many modern IDEs now include MCP servers that let LLMs perform operations within the IDE itself and use IDE tools. Using
+an IDE's MCP server dramatically improves the performance of coding agents. So if you have an IDE, try adding that MCP
+server to your config (see the [MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md) to see how to configure
+them), and modify the agent definition to look like this:
+
+```yaml
+# ...
+
+mcp_servers:
+  - jetbrains # The name of your configured IDE MCP server
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+
+# ...
+```
+

assets/agents/file-reviewer/config.yaml

@@ -0,0 +1,113 @@
+name: file-reviewer
+description: Reviews a single file's diff for bugs, style issues, and cross-cutting concerns
+version: 1.0.0
+temperature: 0.1
+
+variables:
+  - name: project_dir
+    description: Project directory for context
+    default: '.'
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+
+instructions: |
+  You are a precise code reviewer. You review ONE file's diff and produce structured findings.
+
+  ## Your Mission
+
+  You receive a git diff for a single file. Your job:
+  1. Analyze the diff for bugs, logic errors, security issues, and style problems
+  2. Read surrounding code for context (use `fs_read` with targeted offsets)
+  3. Check your inbox for cross-cutting alerts from sibling reviewers
+  4. Send alerts to siblings if you spot cross-file issues
+  5. Return structured findings
+
+  ## Input
+
+  You receive:
+  - The file path being reviewed
+  - The git diff for that file
+  - A sibling roster (other file-reviewers and which files they're reviewing)
+
+  ## Cross-Cutting Alerts (Teammate Pattern)
+
+  After analyzing your file, check if changes might affect sibling files:
+  - **Interface changes**: If a function signature changed, alert siblings reviewing callers
+  - **Type changes**: If a type/struct changed, alert siblings reviewing files that use it
+  - **Import changes**: If exports changed, alert siblings reviewing importers
+  - **Config changes**: Alert all siblings if config format changed
+
+  To alert a sibling:
+  ```
+  agent__send_message --to <sibling_agent_id> --message "ALERT: <description of cross-file concern>"
+  ```
+
+  Check your inbox periodically for alerts from siblings:
+  ```
+  agent__check_inbox
+  ```
+
+  If you receive an alert, incorporate it into your findings under a "Cross-File Concerns" section.
+
+  ## File Reading Strategy
+
+  1. **Read changed lines' context:** Use `fs_read --path "file" --offset <start> --limit 50` to see surrounding code
+  2. **Grep for usage:** `fs_grep --pattern "function_name" --include "*.rs"` to find callers
+  3. **Never read entire large files:** Target the changed regions only
+  4. **Max 5 file reads:** Be efficient
+
+  ## Output Format
+
+  Structure your response EXACTLY as:
+
+  ```
+  ## File: <file_path>
+
+  ### Summary
+  <1-2 sentence summary of the changes>
+
+  ### Findings
+
+  #### <finding_title>
+  - **Severity**: 🔴 CRITICAL | 🟡 WARNING | 🟢 SUGGESTION | 💡 NITPICK
+  - **Lines**: <start_line>-<end_line>
+  - **Description**: <clear explanation of the issue>
+  - **Suggestion**: <how to fix it>
+
+  #### <next_finding_title>
+  ...
+
+  ### Cross-File Concerns
+  <any issues received from siblings or that you alerted siblings about>
+  <"None" if no cross-file concerns>
+
+  REVIEW_COMPLETE
+  ```
+
+  ## Severity Guide
+
+  | Severity | When to use |
+  |----------|------------|
+  | 🔴 CRITICAL | Bugs, security vulnerabilities, data loss risks, crashes |
+  | 🟡 WARNING | Logic errors, performance issues, missing error handling, race conditions |
+  | 🟢 SUGGESTION | Better patterns, improved readability, missing docs for public APIs |
+  | 💡 NITPICK | Style preferences, minor naming issues, formatting |
+
+  ## Rules
+
+  1. **Be specific:** Reference exact line numbers and code
+  2. **Be actionable:** Every finding must have a suggestion
+  3. **Don't nitpick formatting:** If a formatter/linter exists (check for .rustfmt.toml, .prettierrc, etc.)
+  4. **Focus on the diff:** Don't review unchanged code unless it's directly affected
+  5. **Never modify files:** You are read-only
+  6. **Always end with REVIEW_COMPLETE**
+
+  ## Context
+  - Project: {{project_dir}}
+  - CWD: {{__cwd__}}
+  
+  ## Available Tools:
+  {{__tools__}}

assets/agents/file-reviewer/tools.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe File reviewer tools for single-file code review
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# @cmd Get project structure to understand codebase layout
+get_structure() {
+  local project_dir
+  project_dir=$(_project_dir)
+
+  info "Project structure:" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  {
+    echo "Type: $(echo "${project_info}" | jq -r '.type')"
+    echo ""
+    get_tree "${project_dir}" 2
+  } >> "$LLM_OUTPUT"
+}

assets/agents/oracle/README.md

@@ -0,0 +1,39 @@
+# Oracle
+
+An AI agent specialized in high-level architecture, complex debugging, and design decisions.
+
+This agent is designed to be delegated to by the **[Sisyphus](../sisyphus/README.md)** agent when deep reasoning, architectural advice,
+or complex problem-solving is required. Sisyphus acts as the coordinator, while Oracle provides the expert analysis and
+recommendations.
+
+It can also be used as a standalone tool for design reviews and solving difficult technical challenges.
+
+## Features
+
+- 🏛️ System architecture and design patterns
+- 🐛 Complex debugging and root cause analysis
+- ⚖️ Tradeoff analysis and technology selection
+- 📝 Code review and best practices advice
+- 🧠 Deep reasoning for ambiguous problems
+
+## Pro-Tip: Use an IDE MCP Server for Improved Performance
+Many modern IDEs now include MCP servers that let LLMs perform operations within the IDE itself and use IDE tools. Using
+an IDE's MCP server dramatically improves the performance of coding agents. So if you have an IDE, try adding that MCP
+server to your config (see the [MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md) to see how to configure
+them), and modify the agent definition to look like this:
+
+```yaml
+# ...
+
+mcp_servers:
+  - jetbrains # The name of your configured IDE MCP server
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - web_search_loki.sh
+
+# ...
+```

assets/agents/oracle/config.yaml

@@ -0,0 +1,85 @@
+name: oracle
+description: High-IQ advisor for architecture, debugging, and complex decisions
+version: 1.0.0
+temperature: 0.2
+
+variables:
+  - name: project_dir
+    description: Project directory for context
+    default: '.'
+
+mcp_servers:
+  - ddg-search
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+
+instructions: |
+  You are Oracle - a senior architect and debugger consulted for complex decisions.
+  
+  ## Your Role
+  
+  You are READ-ONLY. You analyze, advise, and recommend. You do NOT implement.
+  
+  ## When You're Consulted
+  
+  1. **Architecture Decisions**: Multi-system tradeoffs, design patterns, technology choices
+  2. **Complex Debugging**: After 2+ failed fix attempts, deep analysis needed
+  3. **Code Review**: Evaluating proposed designs or implementations
+  4. **Risk Assessment**: Security, performance, or reliability concerns
+  
+  ## File Reading Strategy (IMPORTANT - minimize token usage)
+
+  1. **Use grep to find relevant code** - `fs_grep --pattern "auth" --include "*.rs"` finds where things are
+  2. **Read only what you need** - `fs_read --path "src/main.rs" --offset 50 --limit 30` reads lines 50-79
+  3. **Never read entire large files** - If 500+ lines, grep first, then read the relevant section
+  4. **Use glob to discover files** - `fs_glob --pattern "*.rs" --path src/`
+
+  ## Your Process
+
+  1. **Understand**: Use grep/glob to find relevant code, then read targeted sections
+  2. **Analyze**: Consider multiple angles and tradeoffs
+  3. **Recommend**: Provide clear, actionable advice
+  4. **Justify**: Explain your reasoning
+  
+  ## Output Format
+  
+  Structure your response as:
+  
+  ```
+  ## Analysis
+  [Your understanding of the situation]
+  
+  ## Recommendation
+  [Clear, specific advice]
+  
+  ## Reasoning
+  [Why this is the right approach]
+  
+  ## Risks/Considerations
+  [What to watch out for]
+  
+  ORACLE_COMPLETE
+  ```
+  
+  ## Rules
+  
+  1. **Never modify files** - You advise, others implement
+  2. **Be thorough** - Read all relevant context before advising
+  3. **Be specific** - General advice isn't helpful
+  4. **Consider tradeoffs** - There are rarely perfect solutions
+  5. **Stay focused** - Answer the specific question asked
+  
+  ## Context
+  - Project: {{project_dir}}
+  - CWD: {{__cwd__}}
+  
+  ## Available Tools:
+  {{__tools__}}
+
+conversation_starters:
+  - 'Review this architecture design'
+  - 'Help debug this complex issue'
+  - 'Evaluate these implementation options'

assets/agents/oracle/tools.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Oracle agent tools for analysis and consultation (read-only)
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# Normalize a path to be relative to project root.
+# Strips the project_dir prefix if the LLM passes an absolute path.
+_normalize_path() {
+  local input_path="$1"
+  local project_dir
+  project_dir=$(_project_dir)
+
+  if [[ "${input_path}" == /* ]]; then
+    input_path="${input_path#"${project_dir}"/}"
+  fi
+
+  input_path="${input_path#./}"
+  echo "${input_path}"
+}
+
+# @cmd Read a file for analysis
+# @option --path! Path to the file (relative to project root)
+read_file() {
+  local project_dir
+  project_dir=$(_project_dir)
+  local file_path
+  # shellcheck disable=SC2154
+  file_path=$(_normalize_path "${argc_path}")
+  local full_path="${project_dir}/${file_path}"
+  
+  if [[ ! -f "${full_path}" ]]; then
+    error "File not found: ${file_path}" >> "$LLM_OUTPUT"
+    return 1
+  fi
+
+  {
+  	info "Reading: ${file_path}"
+  	echo ""
+  	cat "${full_path}"
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Get project structure and type
+get_project_info() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  {
+		info "Project Analysis" >> "$LLM_OUTPUT"
+		cat <<-EOF
+
+			Type: $(echo "${project_info}" | jq -r '.type')
+			Build: $(echo "${project_info}" | jq -r '.build')
+			Test: $(echo "${project_info}" | jq -r '.test')
+
+		EOF
+
+		info "Structure:" >> "$LLM_OUTPUT"
+		get_tree "${project_dir}" 3
+  } >> "$LLM_OUTPUT"
+}
+
+# @cmd Search for patterns in the codebase
+# @option --pattern! Pattern to search for
+# @option --file-type Filter by extension (e.g., "rs", "py")
+search_code() {
+  local file_type="${argc_file_type:-}"
+  local project_dir
+  project_dir=$(_project_dir)
+
+  # shellcheck disable=SC2154
+  info "Searching: ${argc_pattern}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local include_arg=""
+  if [[ -n "${file_type}" ]]; then
+    include_arg="--include=*.${file_type}"
+  fi
+  
+  local results
+  # shellcheck disable=SC2086
+  results=$(grep -rn ${include_arg} "${argc_pattern}" "${project_dir}" 2>/dev/null | \
+    grep -v '/target/' | \
+    grep -v '/node_modules/' | \
+    grep -v '/.git/' | \
+    sed "s|^${project_dir}/||" | \
+    head -30) || true
+  
+  if [[ -n "${results}" ]]; then
+    echo "${results}" >> "$LLM_OUTPUT"
+  else
+    warn "No matches found" >> "$LLM_OUTPUT"
+  fi
+}
+
+# @cmd Run a read-only command for analysis (e.g., git log, cargo tree)
+# @option --command! Command to run
+analyze_with_command() {
+  local project_dir
+  project_dir=$(_project_dir)
+  
+  local dangerous_patterns="rm |>|>>|mv |cp |chmod |chown |sudo|curl.*\\||wget.*\\|"
+  # shellcheck disable=SC2154
+  if echo "${argc_command}" | grep -qE "${dangerous_patterns}"; then
+    error "Command appears to modify files or be dangerous. Oracle is read-only." >> "$LLM_OUTPUT"
+    return 1
+  fi
+  
+  info "Running: ${argc_command}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+  
+  local output
+  output=$(cd "${project_dir}" && eval "${argc_command}" 2>&1) || true
+  echo "${output}" >> "$LLM_OUTPUT"
+}
+
+# @cmd List directory contents
+# @option --path Path to list (default: project root)
+list_directory() {
+  local dir_path
+  dir_path=$(_normalize_path "${argc_path:-.}")
+  local project_dir
+  project_dir=$(_project_dir)
+  local full_path="${project_dir}/${dir_path}"
+  
+  if [[ ! -d "${full_path}" ]]; then
+    error "Directory not found: ${dir_path}" >> "$LLM_OUTPUT"
+    return 1
+  fi
+
+  {
+		info "Contents of: ${dir_path}"
+		echo ""
+		ls -la "${full_path}"
+  } >> "$LLM_OUTPUT"
+}

assets/agents/report-writer/README.md

@@ -0,0 +1,46 @@
+# report-writer
+
+A tiny, focused sub-agent that turns a set of research findings into a
+single coherent final report. Reads only what it is given — does not
+do independent research, does not access the web, does not invent
+facts. It exists as a focused tool for orchestrating agents to
+delegate the writing phase to.
+
+## Why a separate agent?
+
+This is an example of the **agent-as-tool** pattern in graph agents.
+The `deep-research` graph agent's `synthesize` node is an `agent` node
+that spawns this one (see `assets/agents/deep-research/graph.yaml`).
+Separating the role has two practical benefits:
+
+- The orchestrating agent can use a cheap model (or a high-temperature
+  exploratory one) for the research phase, while letting the writing
+  phase use a different (typically lower-temperature, possibly larger)
+  model dedicated to coherent prose.
+- The writing prompt is owned by this agent's `config.yaml` rather
+  than buried inside another agent's graph. You can polish it
+  independently without touching the research flow.
+
+## Standalone use
+
+You can also use this agent directly if you have a set of findings you
+want polished:
+
+```sh
+loki -a report-writer "Topic: X. Findings: <paste findings here>"
+```
+
+It will produce a single Markdown report following the rules in its
+system prompt: executive summary at the top, grouped sections by
+related sub-questions, every inline citation preserved verbatim, and a
+final "Open questions / disagreements" section.
+
+## What it will NOT do
+
+- Search the web, fetch URLs, query an MCP server, or use any tool.
+  It has no tools configured.
+- Invent facts beyond what is in the findings you give it.
+- Strip or rewrite citations.
+
+These constraints are the point of the agent existing: a writer that
+the orchestrator can trust to stay in its lane.

assets/agents/report-writer/config.yaml

@@ -0,0 +1,34 @@
+name: report-writer
+description: Polishes research findings into a clear, citation-preserving final report
+version: 1.0.0
+temperature: 0.2
+
+instructions: |
+  You are a technical writer. You will be given:
+    - a research topic
+    - a set of findings, organized per sub-question, with inline
+      citations next to each claim
+    - a source-credibility assessment of the cited sources
+
+  Your job is to produce a single, well-organized final report:
+
+  Rules:
+    - Use ONLY the findings provided. Do not introduce facts from
+      your own memory. Do not speculate beyond what the findings
+      support.
+    - Preserve every inline citation. If a sentence in the findings
+      had a URL or DOI, the equivalent sentence in your report must
+      keep the same citation.
+    - Lead with a 2-3 sentence executive summary at the top.
+    - Organize the body so that related sub-questions are grouped,
+      not strictly one section per question. The findings are raw
+      material; the report should read as a single coherent answer
+      to the original topic.
+    - End with a short "Open questions / disagreements" section
+      naming anything the findings flagged as unresolved or
+      contested.
+
+  Output plain Markdown. No metadata, no JSON wrapper.
+
+conversation_starters:
+  - "Polish these findings into a cited report"

assets/agents/sisyphus/README.md

@@ -0,0 +1,40 @@
+# Sisyphus
+
+The main coordinator agent for the Loki coding ecosystem, providing a powerful CLI interface for code generation and
+project management similar to OpenCode, ClaudeCode, Codex, or Gemini CLI.
+
+_Inspired by the Sisyphus and Oracle agents of OpenCode._
+
+Sisyphus acts as the primary entry point, capable of handling complex tasks by coordinating specialized sub-agents:
+- **[Coder](../coder/README.md)**: For implementation and file modifications.
+- **[Explore](../explore/README.md)**: For codebase understanding and research.
+- **[Oracle](../oracle/README.md)**: For architecture and complex reasoning.
+
+## Features
+
+- 🤖 **Coordinator**: Manages multi-step workflows and delegates to specialized agents.
+- 💻 **CLI Coding**: Provides a natural language interface for writing and editing code.
+- 🔄 **Task Management**: Tracks progress and context across complex operations.
+- 🛠️ **Tool Integration**: Seamlessly uses system tools for building, testing, and file manipulation.
+
+## Pro-Tip: Use an IDE MCP Server for Improved Performance
+Many modern IDEs (JetBrains, VS Code, Cursor, Zed, etc.) expose MCP servers that let LLMs use IDE tools directly. Using
+one dramatically improves the performance of coding agents. If you have one, add it to your loki config (see the
+[MCP Server docs](../../../docs/function-calling/MCP-SERVERS.md)) and reference it in this agent's `mcp_servers:` list:
+
+```yaml
+# ...
+
+mcp_servers:
+  - your-ide-mcp-server
+
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - web_search_loki.sh
+  - execute_command.sh
+
+# ...
+```

assets/agents/sisyphus/config.yaml

@@ -0,0 +1,258 @@
+name: sisyphus
+description: OpenCode-style orchestrator - classifies intent, delegates to specialists, tracks progress with todos
+version: 2.0.0
+temperature: 0.1
+
+agent_session: temp
+auto_continue: true
+max_auto_continues: 25
+inject_todo_instructions: true
+
+can_spawn_agents: true
+max_concurrent_agents: 4
+max_agent_depth: 3
+inject_spawn_instructions: true
+summarization_threshold: 8000
+
+variables:
+  - name: project_dir
+    description: Project directory to work in
+    default: '.'
+  - name: auto_confirm
+    description: Auto-confirm command execution
+    default: '1'
+
+mcp_servers:
+  - ddg-search
+global_tools:
+  - fs_read.sh
+  - fs_grep.sh
+  - fs_glob.sh
+  - fs_ls.sh
+  - execute_command.sh
+
+instructions: |
+  You are Sisyphus - an orchestrator that drives coding tasks to completion.
+
+  Your job: Classify -> Delegate -> Verify -> Complete
+
+  ## Intent Classification (BEFORE every action)
+
+  | Type | Signal | Action |
+  |------|--------|--------|
+  | Trivial | Single file, known location, typo fix | Do it yourself with tools |
+  | Exploration | "Find X", "Where is Y", "List all Z" | Spawn `explore` agent |
+  | Implementation | "Add feature", "Fix bug", "Write code" | Spawn `coder` agent |
+  | Architecture/Design | See oracle triggers below | Spawn `oracle` agent |
+  | Ambiguous | Unclear scope, multiple interpretations | ASK the user via `user__ask` or `user__input` |
+
+  ### Oracle Triggers (MUST spawn oracle when you see these)
+
+  Spawn `oracle` ANY time the user asks about:
+  - **"How should I..."** / **"What's the best way to..."** -- design/approach questions
+  - **"Why does X keep..."** / **"What's wrong with..."** -- complex debugging (not simple errors)
+  - **"Should I use X or Y?"** -- technology or pattern choices
+  - **"How should this be structured?"** -- architecture and organization
+  - **"Review this"** / **"What do you think of..."** -- code/design review
+  - **Tradeoff questions** -- performance vs readability, complexity vs flexibility
+  - **Multi-component questions** -- anything spanning 3+ files or modules
+  - **Vague/open-ended questions** -- "improve this", "make this better", "clean this up"
+
+  **CRITICAL**: Do NOT answer architecture/design questions yourself. You are a coordinator.
+  Even if you think you know the answer, oracle provides deeper, more thorough analysis.
+  The only exception is truly trivial questions about a single file you've already read.
+
+  ### Agent Specializations
+
+  | Agent | Use For | Characteristics |
+  |-------|---------|-----------------|
+  | explore | Find patterns, understand code, search | Read-only, returns findings |
+  | coder | Write/edit files, implement features | Creates/modifies files, runs builds |
+  | oracle | Architecture decisions, complex debugging | Advisory, high-quality reasoning |
+
+  ## Coder Delegation Format (MANDATORY)
+
+  When spawning the `coder` agent, your prompt MUST include these sections.
+  The coder has NOT seen the codebase. Your prompt IS its entire context.
+
+  ### Template:
+
+  ```
+  ## Goal
+  [1-2 sentences: what to build/modify and where]
+
+  ## Reference Files
+  [Files that explore found, with what each demonstrates]
+  - `path/to/file.ext` - what pattern this file shows
+  - `path/to/other.ext` - what convention this file shows
+
+  ## Code Patterns to Follow
+  [Paste ACTUAL code snippets from explore results, not descriptions]
+  <code>
+  // From path/to/file.ext - this is the pattern to follow:
+  [actual code explore found, 5-20 lines]
+  </code>
+
+  ## Conventions
+  [Naming, imports, error handling, file organization]
+  - Convention 1
+  - Convention 2
+
+  ## Constraints
+  [What NOT to do, scope boundaries]
+  - Do NOT modify X
+  - Only touch files in Y/
+  ```
+
+  **CRITICAL**: Include actual code snippets, not just file paths.
+  If explore returned code patterns, paste them into the coder prompt.
+  Vague prompts like "follow existing patterns" waste coder's tokens on
+  re-exploration that you already did.
+
+  ## Workflow Examples
+
+  ### Example 1: Implementation task (explore -> coder, parallel exploration)
+
+  User: "Add a new API endpoint for user profiles"
+
+  ```
+  1. todo__init --goal "Add user profiles API endpoint"
+  2. todo__add --task "Explore existing API patterns"
+  3. todo__add --task "Implement profile endpoint"
+  4. agent__spawn --agent explore --prompt "Find existing API endpoint patterns, route structures, and controller conventions. Include code snippets."
+  5. agent__spawn --agent explore --prompt "Find existing data models and database query patterns. Include code snippets."
+  6. agent__collect --id <id1>
+  7. agent__collect --id <id2>
+  8. todo__done --id 1
+  9. agent__spawn --agent coder --prompt "<structured prompt using Coder Delegation Format above, including code snippets from explore results>"
+  10. agent__collect --id <coder_id>
+  11. todo__done --id 2
+  ```
+
+  Note: the `coder` agent is a graph agent that runs verification (build +
+  tests) and a bounded fix-loop internally. You do NOT need to spawn a
+  separate build/test step. A `CODER_COMPLETE` outcome means build and
+  tests already passed.
+
+  ### Example 2: Architecture/design question (explore + oracle in parallel)
+
+  User: "How should I structure the authentication for this app?"
+
+  ```
+  1. todo__init --goal "Get architecture advice for authentication"
+  2. todo__add --task "Explore current auth-related code"
+  3. todo__add --task "Consult oracle for architecture recommendation"
+  4. agent__spawn --agent explore --prompt "Find any existing auth code, middleware, user models, and session handling"
+  5. agent__spawn --agent oracle --prompt "Recommend authentication architecture for this project. Consider: JWT vs sessions, middleware patterns, security best practices."
+  6. agent__collect --id <explore_id>
+  7. todo__done --id 1
+  8. agent__collect --id <oracle_id>
+  9. todo__done --id 2
+  ```
+
+  ### Example 3: Vague/open-ended question (oracle directly)
+
+  User: "What do you think of this codebase structure?"
+
+  ```
+  agent__spawn --agent oracle --prompt "Review the project structure and provide recommendations for improvement"
+  agent__collect --id <oracle_id>
+  ```
+
+  ## Rules
+
+  1. **Always classify before acting** - Don't jump into implementation
+  2. **Create todos for multi-step tasks** - Track your progress
+  3. **Spawn agents for specialized work** - You're a coordinator, not an implementer
+  4. **Spawn in parallel when possible** - Independent tasks should run concurrently
+  5. **Verify after collecting agent results** - Don't trust blindly
+  6. **Mark todos done immediately** - Don't batch completions
+  7. **Ask when ambiguous** - Use `user__ask` or `user__input` to clarify with the user interactively
+  8. **Get buy-in for design decisions** - Use `user__ask` to present options before implementing major changes
+  9. **Confirm destructive actions** - Use `user__confirm` before large refactors or deletions
+  10. **Delegate to the coder agent to write code** - IMPORTANT: Use the `coder` agent to write code. Do not try to write code yourself except for trivial changes
+  11. **Always output a summary of changes when finished** - Make it clear to user's that you've completed your tasks
+
+  ## Coder Outcomes
+
+  The `coder` agent is a graph agent that runs the implement -> verify_build
+  -> verify_tests -> fix_loop pipeline internally. It always returns one of
+  three sentinel outcomes:
+
+  - `CODER_COMPLETE` - implementation succeeded with build + tests green.
+    Continue with any follow-up todos.
+  - `CODER_REJECTED` - user rejected the plan at the approval gate (only
+    triggered for high-complexity plans). Do NOT re-spawn coder blindly;
+    ask the user what to change first.
+  - `CODER_FAILED` - the fix-loop exhausted its budget without producing
+    green build/tests. The failure output includes the last build and tests
+    output. Surface this to the user; consider spawning `oracle` for
+    diagnosis if the failure is unclear.
+
+  ## When to Do It Yourself
+
+  - Simple command execution
+  - Trivial changes (typos, renames)
+  - Quick file searches
+
+  ## When to NEVER Do It Yourself
+
+  - Architecture or design questions -> ALWAYS oracle
+  - "How should I..." / "What's the best way to..." -> ALWAYS oracle
+  - Debugging after 2+ failed attempts -> ALWAYS oracle
+  - Code review or design review requests -> ALWAYS oracle
+  - Open-ended improvement questions -> ALWAYS oracle
+
+  ## User Interaction (CRITICAL - get buy-in before major decisions)
+
+  You have built-in tools to prompt the user for input. Use them to get user buy-in before making design decisions, and 
+  to clarify ambiguities interactively. **Do NOT guess when you can ask.**
+
+  ### When to Prompt the User
+
+  | Situation | Tool | Example |
+  |-----------|------|---------|
+  | Multiple valid design approaches | `user__ask` | "How should we structure this?" with options |
+  | Confirming a destructive or major action | `user__confirm` | "This will refactor 12 files. Proceed?" |
+  | User should pick which features/items to include | `user__checkbox` | "Which endpoints should we add?" |
+  | Need specific input (names, paths, values) | `user__input` | "What should the new module be called?" |
+  | Ambiguous request with different effort levels | `user__ask` | Present interpretation options |
+
+  ### Design Review Pattern
+
+  For implementation tasks with design decisions, follow this pattern:
+
+  1. **Explore** the codebase to understand existing patterns
+  2. **Formulate** 2-3 design options based on findings
+  3. **Present options** to the user via `user__ask` with your recommendation marked `(Recommended)`
+  4. **Confirm** the chosen approach before delegating to `coder`
+  5. Proceed with implementation
+
+  ### Rules for User Prompts
+
+  1. **Always include (Recommended)** on the option you think is best in `user__ask`
+  2. **Respect user choices** - never override or ignore a selection
+  3. **Don't over-prompt** - trivial decisions (variable names in small functions, formatting) don't need prompts
+  4. **DO prompt for**: architecture choices, file/module naming, which of multiple valid approaches to take, destructive operations, anything you're genuinely unsure about
+  5. **Confirm before large changes** - if a task will touch 5+ files, confirm the plan first
+
+  ## Escalation Handling
+
+  If you see `pending_escalations` in your tool results, a child agent needs user input and is blocked.
+  Reply promptly via `agent__reply_escalation` to unblock it. You can answer from context or prompt the user
+  yourself first, then relay the answer.
+
+  ## Available Tools
+  {{__tools__}}
+
+  ## Context
+  - Project: {{project_dir}}
+  - OS: {{__os__}}
+  - Shell: {{__shell__}}
+  - CWD: {{__cwd__}}
+
+conversation_starters:
+  - 'Add a new feature to the project'
+  - 'Fix a bug in the codebase'
+  - 'Refactor the authentication module'
+  - 'Help me understand how X works'

assets/agents/sisyphus/tools.sh

@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+set -eo pipefail
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+source "$LLM_ROOT_DIR/agents/.shared/utils.sh"
+export AUTO_CONFIRM=true
+
+# @env LLM_OUTPUT=/dev/stdout
+# @env LLM_AGENT_VAR_PROJECT_DIR=.
+# @describe Sisyphus orchestrator tools (project info, build, test)
+
+_project_dir() {
+  local dir="${LLM_AGENT_VAR_PROJECT_DIR:-.}"
+  (cd "${dir}" 2>/dev/null && pwd) || echo "${dir}"
+}
+
+# @cmd Get project information and structure
+get_project_info() {
+  local project_dir
+  project_dir=$(_project_dir)
+
+  info "Project: ${project_dir}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+
+  cat <<-EOF >> "$LLM_OUTPUT"
+		Type: $(echo "${project_info}" | jq -r '.type')
+		Build: $(echo "${project_info}" | jq -r '.build')
+		Test: $(echo "${project_info}" | jq -r '.test')
+
+		$(info "Directory structure:")
+		$(get_tree "${project_dir}" 2)
+	EOF
+}
+
+# @cmd Run build command for the project
+run_build() {
+  local project_dir
+  project_dir=$(_project_dir)
+
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+  local build_cmd
+  build_cmd=$(echo "${project_info}" | jq -r '.build')
+
+  if [[ -z "${build_cmd}" ]] || [[ "${build_cmd}" == "null" ]]; then
+    warn "No build command detected for this project" >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  info "Running: ${build_cmd}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+
+  local output
+  if output=$(cd "${project_dir}" && eval "${build_cmd}" 2>&1); then
+    green "BUILD SUCCESS" >> "$LLM_OUTPUT"
+    echo "${output}" >> "$LLM_OUTPUT"
+    return 0
+  else
+    error "BUILD FAILED" >> "$LLM_OUTPUT"
+    echo "${output}" >> "$LLM_OUTPUT"
+    return 1
+  fi
+}
+
+# @cmd Run tests for the project
+run_tests() {
+  local project_dir
+  project_dir=$(_project_dir)
+
+  local project_info
+  project_info=$(detect_project "${project_dir}")
+  local test_cmd
+  test_cmd=$(echo "${project_info}" | jq -r '.test')
+
+  if [[ -z "${test_cmd}" ]] || [[ "${test_cmd}" == "null" ]]; then
+    warn "No test command detected for this project" >> "$LLM_OUTPUT"
+    return 0
+  fi
+
+  info "Running: ${test_cmd}" >> "$LLM_OUTPUT"
+  echo "" >> "$LLM_OUTPUT"
+
+  local output
+  if output=$(cd "${project_dir}" && eval "${test_cmd}" 2>&1); then
+    green "TESTS PASSED" >> "$LLM_OUTPUT"
+    echo "${output}" >> "$LLM_OUTPUT"
+    return 0
+  else
+    error "TESTS FAILED" >> "$LLM_OUTPUT"
+    echo "${output}" >> "$LLM_OUTPUT"
+    return 1
+  fi
+}
+

assets/agents/sql/README.md

@@ -0,0 +1,5 @@
+# SQL
+
+An AI agent that helps you manage a SQL database.
+
+> The tool script uses [usql](https://github.com/xo/usql) to interact with SQL, it supports all mainstream databases. 

assets/agents/sql/config.yaml

@@ -0,0 +1,17 @@
+name: Sql
+description: An AI agent that helps you manage any SQL database
+version: 0.1.0
+instructions: |
+  You are an AI agent that manages a SQL database.
+  Prefix all referenced tables with the name of the schema that they are in.
+
+  For all sqlite databases, prefix each table name with 'main' as the schema
+
+
+  Available tools:
+  {{__tools__}}
+variables:
+  - name: dsn
+    description: The database connection url. e.g. pgsql://user:pass@host:port
+conversation_starters:
+  - What you can do?

assets/agents/sql/tools.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+set -e
+
+# @meta require-tools usql
+# @env LLM_OUTPUT=/dev/stdout The output path
+# @env LLM_AGENT_VAR_DSN! The database connection url. e.g. pgsql://user:pass@host:port 
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+
+# @cmd Execute a SELECT query
+# @option --query!                  SELECT SQL query to execute
+read_query() {
+    # shellcheck disable=SC2154
+    if ! grep -qi '^select' <<<"$argc_query"; then
+        error "only SELECT queries are allowed" >&2
+        exit 1
+    fi
+
+    _run_sql "$argc_query"
+}
+
+# @cmd Execute an SQL query
+# @option --query!                  SQL query to execute
+write_query() {
+    guard_operation "Execute SQL?"
+    _run_sql "$argc_query"
+}
+
+# @cmd List all tables
+list_tables() {
+    _run_sql "\dt+"
+}
+
+# @cmd Get the schema information for a specific table
+# @option --table-name!             Name of the table to describe
+describe_table() {
+    # shellcheck disable=SC2154
+    _run_sql "\d $argc_table_name"
+}
+
+_run_sql() {
+    usql "$LLM_AGENT_VAR_DSN" -c "$1" >> "$LLM_OUTPUT"
+}

assets/functions/mcp.json

@@ -0,0 +1,34 @@
+{
+  "mcpServers": {
+    "github": {
+      "type": "stdio",
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN"
+      }
+    },
+    "atlassian": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "mcp-remote@0.1.13", "https://mcp.atlassian.com/v1/mcp"]
+    },
+    "docker": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-server-docker"]
+    },
+    "ddg-search": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["duckduckgo-mcp-server"]
+    }
+  }
+}

assets/functions/scripts/run-agent.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python
+
+# Usage: ./{agent_name}.py <agent-func> <agent-data>
+
+import os
+import re
+import json
+import sys
+import importlib.util
+from pathlib import Path
+
+def _ensure_cwd_venv():
+    cwd = Path.cwd()
+    venv_dir = cwd / ".venv"
+    if not venv_dir.is_dir():
+        return
+
+    py = venv_dir / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+    if not py.exists():
+        return
+
+    if Path(sys.prefix).resolve() == venv_dir.resolve():
+        return
+
+    os.execv(str(py), [str(py)] + sys.argv)
+
+_ensure_cwd_venv()
+
+
+def main():
+    (agent_func, raw_data) = parse_argv()
+    agent_data = parse_raw_data(raw_data)
+
+    root_dir = "{config_dir}"
+    setup_env(root_dir, agent_func)
+
+    agent_tools_path = os.path.join(root_dir, "agents/{agent_name}/tools.py")
+    run(agent_tools_path, agent_func, agent_data)
+
+
+def parse_raw_data(data):
+    if not data:
+        raise ValueError("No JSON data")
+
+    try:
+        return json.loads(data)
+    except Exception:
+        raise ValueError("Invalid JSON data")
+
+
+def parse_argv():
+    agent_func = sys.argv[1]
+
+    tool_data_file = os.environ.get("LLM_TOOL_DATA_FILE")
+    if tool_data_file and os.path.isfile(tool_data_file):
+        with open(tool_data_file, "r", encoding="utf-8") as f:
+            agent_data = f.read()
+    else:
+        agent_data = sys.argv[2]
+
+    if (not agent_data) or (not agent_func):
+        print("Usage: ./{agent_name}.py <agent-func> <agent-data>", file=sys.stderr)
+        sys.exit(1)   
+
+    return agent_func, agent_data
+
+
+def setup_env(root_dir, agent_func):
+    load_env(os.path.join(root_dir, ".env"))
+    os.environ["LLM_ROOT_DIR"] = root_dir
+    os.environ["LLM_AGENT_NAME"] = "{agent_name}"
+    os.environ["LLM_AGENT_FUNC"] = agent_func
+    os.environ["LLM_AGENT_ROOT_DIR"] = os.path.join(root_dir, "agents", "{agent_name}")
+    os.environ["LLM_AGENT_CACHE_DIR"] = os.path.join(root_dir, "cache", "{agent_name}")
+
+
+def load_env(file_path):
+    try:
+        with open(file_path, "r") as f:
+            lines = f.readlines()
+    except:
+        return
+
+    env_vars = {}
+
+    for line in lines:
+        line = line.strip()
+        if line.startswith("#") or not line:
+            continue
+
+        key, *value_parts = line.split("=")
+        env_name = key.strip()
+
+        if env_name not in os.environ:
+            env_value = "=".join(value_parts).strip()
+            if (env_value.startswith('"') and env_value.endswith('"')) or (env_value.startswith("'") and env_value.endswith("'")):
+                env_value = env_value[1:-1]
+            env_vars[env_name] = env_value
+
+    os.environ.update(env_vars)
+
+
+def run(agent_path, agent_func, agent_data):
+    spec = importlib.util.spec_from_file_location(
+        os.path.basename(agent_path), agent_path
+    )
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    if not hasattr(mod, agent_func):
+        raise Exception(f"Not module function '{agent_func}' at '{agent_path}'")
+
+    value = getattr(mod, agent_func)(**agent_data)
+    return_to_llm(value)
+    dump_result('{agent_name}' + f':{agent_func}')
+
+
+def return_to_llm(value):
+    if value is None:
+        return
+
+    if "LLM_OUTPUT" in os.environ:
+        writer = open(os.environ["LLM_OUTPUT"], "w")
+    else:
+        writer = sys.stdout
+
+    value_type = type(value).__name__
+    if value_type in ("str", "int", "float", "bool"):
+        writer.write(str(value))
+    elif value_type == "dict" or value_type == "list":
+        value_str = json.dumps(value, indent=2)
+        assert value == json.loads(value_str)
+        writer.write(value_str)
+
+
+def dump_result(name):
+    if (not os.getenv("LLM_DUMP_RESULTS")) or (not os.getenv("LLM_OUTPUT")) or (not os.isatty(1)):
+        return
+
+    show_result = False
+    try:
+        if re.search(rf'\b({os.environ["LLM_DUMP_RESULTS"]})\b', name):
+            show_result = True
+    except:
+        pass
+
+    if not show_result:
+        return
+
+    try:
+        with open(os.environ["LLM_OUTPUT"], "r", encoding="utf-8") as f:
+            data = f.read()
+    except:
+        return
+
+    print(f"\x1b[2m----------------------\n{data}\n----------------------\x1b[0m")
+
+
+if __name__ == "__main__":
+    main()

assets/functions/scripts/run-agent.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+
+# Usage: ./{agent_name}.sh <agent-func> <agent-data>
+
+set -e
+
+main() {
+    root_dir="{config_dir}"
+    parse_argv "$@"
+    setup_env
+    tools_path="$root_dir/agents/{agent_name}/tools.sh"
+    run
+}
+
+parse_argv() {
+		agent_func="$1"
+    if [[ -n "$LLM_TOOL_DATA_FILE" ]] && [[ -f "$LLM_TOOL_DATA_FILE" ]]; then
+      	agent_data="$(cat "$LLM_TOOL_DATA_FILE")"
+    else
+				agent_data="$2"
+    fi
+    if [[ -z "$agent_data" ]] || [[ -z "$agent_func" ]]; then
+        die "usage: ./{agent_name}.sh <agent-func> <agent-data>"
+    fi
+}
+
+setup_env() {
+    load_env "$root_dir/.env"
+    export LLM_ROOT_DIR="$root_dir"
+    export LLM_AGENT_NAME="{agent_name}"
+    export LLM_AGENT_FUNC="$agent_func"
+    export LLM_AGENT_ROOT_DIR="$LLM_ROOT_DIR/agents/{agent_name}"
+    export LLM_AGENT_CACHE_DIR="$LLM_ROOT_DIR/cache/{agent_name}"
+    export LLM_PROMPT_UTILS_FILE="{prompt_utils_file}"
+}
+
+load_env() {
+    local env_file="$1" env_vars
+    if [[ -f "$env_file" ]]; then
+        while IFS='=' read -r key value; do
+            if [[ "$key" == $'#'* ]] || [[ -z "$key" ]]; then
+                continue
+            fi
+
+            if [[ -z "${!key+x}" ]]; then
+                env_vars="$env_vars $key=$value"
+            fi
+        done < <(cat "$env_file"; echo "")
+
+        if [[ -n "$env_vars" ]]; then
+            eval "export $env_vars"
+        fi
+    fi
+}
+
+run() {
+    if [[ -z "$agent_data" ]]; then
+        die "error: no JSON data"
+    fi
+
+    if [[ "$OS" == "Windows_NT" ]]; then
+        set -o igncr
+        tools_path="$(cygpath -w "$tools_path")"
+    fi
+
+    jq_script="$(cat <<-'EOF'
+def escape_shell_word:
+  tostring
+  | gsub("'"; "'\"'\"'")
+  | gsub("\n"; "'$'\\n''")
+  | "'\(.)'";
+def to_args:
+    to_entries | .[] |
+    (.key | split("_") | join("-")) as $key |
+    if .value | type == "array" then
+        .value | .[] | "--\($key)=\(. | escape_shell_word)"
+    elif .value | type == "boolean" then
+        if .value then "--\($key)" else "" end
+    else
+        "--\($key)=\(.value | escape_shell_word)"
+    end;
+[ to_args ] | join(" ")
+EOF
+)"
+    args="$(echo "$agent_data" | jq -r "$jq_script" 2>/dev/null)" || {
+        die "error: invalid JSON data"
+    }
+
+    if [[ -z "$LLM_OUTPUT" ]]; then
+        is_temp_llm_output=1
+        # shellcheck disable=SC2155
+        export LLM_OUTPUT="$(mktemp)"
+    fi
+
+    eval "'$tools_path' '$agent_func' $args"
+
+    if [[ "$is_temp_llm_output" -eq 1 ]]; then
+        cat "$LLM_OUTPUT"
+    else
+        dump_result "{agent_name}:${LLM_AGENT_FUNC}"
+    fi
+}
+
+dump_result() {
+    if [[ "$LLM_OUTPUT" == "/dev/stdout" ]] || [[ -z "$LLM_DUMP_RESULTS" ]] ||  [[ ! -t 1 ]]; then
+        return;
+    fi
+
+    if grep -q -w -E "$LLM_DUMP_RESULTS" <<<"$1"; then
+        cat <<EOF
+$(echo -e "\e[2m")----------------------
+$(cat "$LLM_OUTPUT")
+----------------------$(echo -e "\e[0m")
+EOF
+    fi
+}
+
+die() {
+    echo "$*" >&2
+    exit 1
+}
+
+main "$@"
+

assets/functions/scripts/run-agent.ts

@@ -0,0 +1,189 @@
+#!/usr/bin/env tsx
+
+// Usage: ./{agent_name}.ts <agent-func> <agent-data>
+
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
+
+async function main(): Promise<void> {
+  const { agentFunc, rawData } = parseArgv();
+  const agentData = parseRawData(rawData);
+
+  const configDir = "{config_dir}";
+  setupEnv(configDir, agentFunc);
+
+  const agentToolsPath = join(configDir, "agents", "{agent_name}", "tools.ts");
+  await run(agentToolsPath, agentFunc, agentData);
+}
+
+function parseRawData(data: string): Record<string, unknown> {
+  if (!data) {
+    throw new Error("No JSON data");
+  }
+
+  try {
+    return JSON.parse(data);
+  } catch {
+    throw new Error("Invalid JSON data");
+  }
+}
+
+function parseArgv(): { agentFunc: string; rawData: string } {
+  const agentFunc = process.argv[2];
+
+  const toolDataFile = process.env["LLM_TOOL_DATA_FILE"];
+  let agentData: string;
+  if (toolDataFile && existsSync(toolDataFile)) {
+    agentData = readFileSync(toolDataFile, "utf-8");
+  } else {
+    agentData = process.argv[3];
+  }
+
+  if (!agentFunc || !agentData) {
+    process.stderr.write("Usage: ./{agent_name}.ts <agent-func> <agent-data>\n");
+    process.exit(1);
+  }
+
+  return { agentFunc, rawData: agentData };
+}
+
+function setupEnv(configDir: string, agentFunc: string): void {
+  loadEnv(join(configDir, ".env"));
+  process.env["LLM_ROOT_DIR"] = configDir;
+  process.env["LLM_AGENT_NAME"] = "{agent_name}";
+  process.env["LLM_AGENT_FUNC"] = agentFunc;
+  process.env["LLM_AGENT_ROOT_DIR"] = join(configDir, "agents", "{agent_name}");
+  process.env["LLM_AGENT_CACHE_DIR"] = join(configDir, "cache", "{agent_name}");
+}
+
+function loadEnv(filePath: string): void {
+  let lines: string[];
+  try {
+    lines = readFileSync(filePath, "utf-8").split("\n");
+  } catch {
+    return;
+  }
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.startsWith("#") || !line) {
+      continue;
+    }
+
+    const eqIdx = line.indexOf("=");
+    if (eqIdx === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, eqIdx).trim();
+    if (key in process.env) {
+      continue;
+    }
+
+    let value = line.slice(eqIdx + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    process.env[key] = value;
+  }
+}
+
+function extractParamNames(fn: Function): string[] {
+  const src = fn.toString();
+  const match = src.match(/^(?:async\s+)?function\s*\w*\s*\(([^)]*)\)/);
+  if (!match) {
+    return [];
+  }
+  return match[1]
+    .split(",")
+    .map((p) => p.trim().replace(/[:=?].*/s, "").trim())
+    .filter(Boolean);
+}
+
+function spreadArgs(
+  fn: Function,
+  data: Record<string, unknown>,
+): unknown[] {
+  const names = extractParamNames(fn);
+  if (names.length === 0) {
+    return [];
+  }
+  return names.map((name) => data[name]);
+}
+
+async function run(
+  agentPath: string,
+  agentFunc: string,
+  agentData: Record<string, unknown>,
+): Promise<void> {
+  const mod = await import(pathToFileURL(agentPath).href);
+
+  if (typeof mod[agentFunc] !== "function") {
+    throw new Error(`No module function '${agentFunc}' at '${agentPath}'`);
+  }
+
+  const fn = mod[agentFunc] as Function;
+  const args = spreadArgs(fn, agentData);
+  const value = await fn(...args);
+  returnToLlm(value);
+  dumpResult(`{agent_name}:${agentFunc}`);
+}
+
+function returnToLlm(value: unknown): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+
+  const output = process.env["LLM_OUTPUT"];
+  const write = (s: string) => {
+    if (output) {
+      writeFileSync(output, s, "utf-8");
+    } else {
+      process.stdout.write(s);
+    }
+  };
+
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    write(String(value));
+  } else if (typeof value === "object") {
+    write(JSON.stringify(value, null, 2));
+  }
+}
+
+function dumpResult(name: string): void {
+  const dumpResults = process.env["LLM_DUMP_RESULTS"];
+  const llmOutput = process.env["LLM_OUTPUT"];
+
+  if (!dumpResults || !llmOutput || !process.stdout.isTTY) {
+    return;
+  }
+
+  try {
+    const pattern = new RegExp(`\\b(${dumpResults})\\b`);
+    if (!pattern.test(name)) {
+      return;
+    }
+  } catch {
+    return;
+  }
+
+  let data: string;
+  try {
+    data = readFileSync(llmOutput, "utf-8");
+  } catch {
+    return;
+  }
+
+  process.stdout.write(
+    `\x1b[2m----------------------\n${data}\n----------------------\x1b[0m\n`,
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err}\n`);
+  process.exit(1);
+});

assets/functions/scripts/run-tool.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python
+
+# Usage: ./{function_name}.py <tool-data>
+
+import os
+import re
+import json
+import sys
+import importlib.util
+from pathlib import Path
+
+def _ensure_cwd_venv():
+    cwd = Path.cwd()
+    venv_dir = cwd / ".venv"
+    if not venv_dir.is_dir():
+        return
+
+    py = venv_dir / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
+    if not py.exists():
+        return
+
+    if Path(sys.prefix).resolve() == venv_dir.resolve():
+        return
+
+    os.execv(str(py), [str(py)] + sys.argv)
+
+_ensure_cwd_venv()
+
+
+def main():
+    raw_data = parse_argv()
+    tool_data = parse_raw_data(raw_data)
+
+    root_dir = "{root_dir}"
+    setup_env(root_dir)
+
+    tool_path = "{tool_path}.py"
+    run(tool_path, "run", tool_data)
+
+
+def parse_raw_data(data):
+    if not data:
+        raise ValueError("No JSON data")
+
+    try:
+        return json.loads(data)
+    except Exception:
+        raise ValueError("Invalid JSON data")
+
+
+def parse_argv():
+    tool_data_file = os.environ.get("LLM_TOOL_DATA_FILE")
+    if tool_data_file and os.path.isfile(tool_data_file):
+        with open(tool_data_file, "r", encoding="utf-8") as f:
+            return f.read()
+
+    argv = sys.argv[:] + [None] * max(0, 2 - len(sys.argv))
+
+    tool_data = argv[1]
+
+    if (not tool_data):
+        print("Usage: ./{function_name}.py <tool-data>", file=sys.stderr)
+        sys.exit(1)
+
+    return tool_data
+
+
+def setup_env(root_dir):
+    load_env(os.path.join(root_dir, ".env"))
+    os.environ["LLM_ROOT_DIR"] = root_dir
+    os.environ["LLM_TOOL_NAME"] = "{function_name}"
+    os.environ["LLM_TOOL_CACHE_DIR"] = os.path.join(root_dir, "cache", "{function_name}")
+
+
+def load_env(file_path):
+    try:
+        with open(file_path, "r") as f:
+            lines = f.readlines()
+    except:
+        return
+
+    env_vars = {}
+
+    for line in lines:
+        line = line.strip()
+        if line.startswith("#") or not line:
+            continue
+
+        key, *value_parts = line.split("=")
+        env_name = key.strip()
+
+        if env_name not in os.environ:
+            env_value = "=".join(value_parts).strip()
+            if (env_value.startswith('"') and env_value.endswith('"')) or (env_value.startswith("'") and env_value.endswith("'")):
+                env_value = env_value[1:-1]
+            env_vars[env_name] = env_value
+
+    os.environ.update(env_vars)
+
+
+def run(tool_path, tool_func, tool_data):
+    spec = importlib.util.spec_from_file_location(
+        os.path.basename(tool_path), tool_path
+    )
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+
+    if not hasattr(mod, tool_func):
+        raise Exception(f"No module function '{tool_func}' at '{tool_path}'")
+
+    value = getattr(mod, tool_func)(**tool_data)
+    return_to_llm(value)
+    dump_result("{function_name}")
+
+
+def return_to_llm(value):
+    if value is None:
+        return
+
+    if "LLM_OUTPUT" in os.environ:
+        writer = open(os.environ["LLM_OUTPUT"], "w")
+    else:
+        writer = sys.stdout
+
+    value_type = type(value).__name__
+    if value_type in ("str", "int", "float", "bool"):
+        writer.write(str(value))
+    elif value_type == "dict" or value_type == "list":
+        value_str = json.dumps(value, indent=2)
+        assert value == json.loads(value_str)
+        writer.write(value_str)
+
+
+def dump_result(name):
+    if (not os.getenv("LLM_DUMP_RESULTS")) or (not os.getenv("LLM_OUTPUT")) or (not os.isatty(1)):
+        return
+
+    show_result = False
+    try:
+        if re.search(rf'\b({os.environ["LLM_DUMP_RESULTS"]})\b', name):
+            show_result = True
+    except:
+        pass
+
+    if not show_result:
+        return
+
+    try:
+        with open(os.environ["LLM_OUTPUT"], "r", encoding="utf-8") as f:
+            data = f.read()
+    except:
+        return
+
+    print(f"\x1b[2m----------------------\n{data}\n----------------------\x1b[0m")
+
+
+if __name__ == "__main__":
+    main()

assets/functions/scripts/run-tool.sh

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+
+# Usage: ./{function_name}.sh <tool-data>
+
+set -e
+
+main() {
+    root_dir="{root_dir}"
+    parse_argv "$@"
+    setup_env
+    tool_path="{tool_path}.sh"
+    run
+}
+
+parse_argv() {
+    if [[ -n "$LLM_TOOL_DATA_FILE" ]] && [[ -f "$LLM_TOOL_DATA_FILE" ]]; then
+        tool_data="$(cat "$LLM_TOOL_DATA_FILE")"
+    else
+				tool_data="$1"
+    fi
+    if [[ -z "$tool_data" ]]; then
+        die "usage: ./{function_name}.sh <tool-data>"
+    fi
+}
+
+setup_env() {
+    load_env "$root_dir/.env"
+    export LLM_ROOT_DIR="$root_dir"
+    export LLM_TOOL_NAME="{function_name}"
+    export LLM_TOOL_CACHE_DIR="$LLM_ROOT_DIR/cache/{function_name}"
+    export LLM_PROMPT_UTILS_FILE="{prompt_utils_file}"
+}
+
+load_env() {
+    local env_file="$1" env_vars
+    if [[ -f "$env_file" ]]; then
+        while IFS='=' read -r key value; do
+            if [[ "$key" == $'#'* ]] || [[ -z "$key" ]]; then
+                continue
+            fi
+
+            if [[ -z "${!key+x}" ]]; then
+                env_vars="$env_vars $key=$value"
+            fi
+        done < <(cat "$env_file"; echo "")
+
+        if [[ -n "$env_vars" ]]; then
+            eval "export $env_vars"
+        fi
+    fi
+}
+
+run() {
+    if [[ -z "$tool_data" ]]; then
+        die "error: no JSON data"
+    fi
+
+    if [[ "$OS" == "Windows_NT" ]]; then
+        set -o igncr
+        tool_path="$(cygpath -w "$tool_path")"
+    fi
+
+    jq_script="$(cat <<-'EOF'
+def escape_shell_word:
+  tostring
+  | gsub("'"; "'\"'\"'")
+  | gsub("\n"; "'$'\\n''")
+  | "'\(.)'";
+def to_args:
+    to_entries | .[] |
+    (.key | split("_") | join("-")) as $key |
+    if .value | type == "array" then
+        .value | .[] | "--\($key)=\(. | escape_shell_word)"
+    elif .value | type == "boolean" then
+        if .value then "--\($key)" else "" end
+    else
+        "--\($key)=\(.value | escape_shell_word)"
+    end;
+[ to_args ] | join(" ")
+EOF
+)"
+    args="$(echo "$tool_data" | jq -r "$jq_script" 2>/dev/null)" || {
+        die "error: invalid JSON data"
+    }
+
+    if [[ -z "$LLM_OUTPUT" ]]; then
+        is_temp_llm_output=1
+        # shellcheck disable=SC2155
+        export LLM_OUTPUT="$(mktemp)"
+    fi
+
+    eval "'$tool_path' $args"
+
+    if [[ "$is_temp_llm_output" -eq 1 ]]; then
+        cat "$LLM_OUTPUT"
+    else
+        dump_result "{function_name}"
+    fi
+}
+
+dump_result() {
+    if [[ "$LLM_OUTPUT" == "/dev/stdout" ]] || [[ -z "$LLM_DUMP_RESULTS" ]] ||  [[ ! -t 1 ]]; then
+        return;
+    fi
+
+    if grep -q -w -E "$LLM_DUMP_RESULTS" <<<"$1"; then
+        cat <<EOF
+$(echo -e "\e[2m")----------------------
+$(cat "$LLM_OUTPUT")
+----------------------$(echo -e "\e[0m")
+EOF
+    fi
+}
+
+die() {
+    echo "$*" >&2
+    exit 1
+}
+
+main "$@"

assets/functions/scripts/run-tool.ts

@@ -0,0 +1,184 @@
+#!/usr/bin/env tsx
+
+// Usage: ./{function_name}.ts <tool-data>
+
+import { readFileSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import { pathToFileURL } from "url";
+
+async function main(): Promise<void> {
+  const rawData = parseArgv();
+  const toolData = parseRawData(rawData);
+
+  const rootDir = "{root_dir}";
+  setupEnv(rootDir);
+
+  const toolPath = "{tool_path}.ts";
+  await run(toolPath, "run", toolData);
+}
+
+function parseRawData(data: string): Record<string, unknown> {
+  if (!data) {
+    throw new Error("No JSON data");
+  }
+
+  try {
+    return JSON.parse(data);
+  } catch {
+    throw new Error("Invalid JSON data");
+  }
+}
+
+function parseArgv(): string {
+  const toolDataFile = process.env["LLM_TOOL_DATA_FILE"];
+  if (toolDataFile && existsSync(toolDataFile)) {
+    return readFileSync(toolDataFile, "utf-8");
+  }
+
+  const toolData = process.argv[2];
+
+  if (!toolData) {
+    process.stderr.write("Usage: ./{function_name}.ts <tool-data>\n");
+    process.exit(1);
+  }
+
+  return toolData;
+}
+
+function setupEnv(rootDir: string): void {
+  loadEnv(join(rootDir, ".env"));
+  process.env["LLM_ROOT_DIR"] = rootDir;
+  process.env["LLM_TOOL_NAME"] = "{function_name}";
+  process.env["LLM_TOOL_CACHE_DIR"] = join(rootDir, "cache", "{function_name}");
+}
+
+function loadEnv(filePath: string): void {
+  let lines: string[];
+  try {
+    lines = readFileSync(filePath, "utf-8").split("\n");
+  } catch {
+    return;
+  }
+
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (line.startsWith("#") || !line) {
+      continue;
+    }
+
+    const eqIdx = line.indexOf("=");
+    if (eqIdx === -1) {
+      continue;
+    }
+
+    const key = line.slice(0, eqIdx).trim();
+    if (key in process.env) {
+      continue;
+    }
+
+    let value = line.slice(eqIdx + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    process.env[key] = value;
+  }
+}
+
+function extractParamNames(fn: Function): string[] {
+  const src = fn.toString();
+  const match = src.match(/^(?:async\s+)?function\s*\w*\s*\(([^)]*)\)/);
+  if (!match) {
+    return [];
+  }
+  return match[1]
+    .split(",")
+    .map((p) => p.trim().replace(/[:=?].*/s, "").trim())
+    .filter(Boolean);
+}
+
+function spreadArgs(
+  fn: Function,
+  data: Record<string, unknown>,
+): unknown[] {
+  const names = extractParamNames(fn);
+  if (names.length === 0) {
+    return [];
+  }
+  return names.map((name) => data[name]);
+}
+
+async function run(
+  toolPath: string,
+  toolFunc: string,
+  toolData: Record<string, unknown>,
+): Promise<void> {
+  const mod = await import(pathToFileURL(toolPath).href);
+
+  if (typeof mod[toolFunc] !== "function") {
+    throw new Error(`No module function '${toolFunc}' at '${toolPath}'`);
+  }
+
+  const fn = mod[toolFunc] as Function;
+  const args = spreadArgs(fn, toolData);
+  const value = await fn(...args);
+  returnToLlm(value);
+  dumpResult("{function_name}");
+}
+
+function returnToLlm(value: unknown): void {
+  if (value === null || value === undefined) {
+    return;
+  }
+
+  const output = process.env["LLM_OUTPUT"];
+  const write = (s: string) => {
+    if (output) {
+      writeFileSync(output, s, "utf-8");
+    } else {
+      process.stdout.write(s);
+    }
+  };
+
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    write(String(value));
+  } else if (typeof value === "object") {
+    write(JSON.stringify(value, null, 2));
+  }
+}
+
+function dumpResult(name: string): void {
+  const dumpResults = process.env["LLM_DUMP_RESULTS"];
+  const llmOutput = process.env["LLM_OUTPUT"];
+
+  if (!dumpResults || !llmOutput || !process.stdout.isTTY) {
+    return;
+  }
+
+  try {
+    const pattern = new RegExp(`\\b(${dumpResults})\\b`);
+    if (!pattern.test(name)) {
+      return;
+    }
+  } catch {
+    return;
+  }
+
+  let data: string;
+  try {
+    data = readFileSync(llmOutput, "utf-8");
+  } catch {
+    return;
+  }
+
+  process.stdout.write(
+    `\x1b[2m----------------------\n${data}\n----------------------\x1b[0m\n`,
+  );
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err}\n`);
+  process.exit(1);
+});

assets/functions/tools/demo_py.py

@@ -0,0 +1,51 @@
+import os
+from typing import List, Literal, Optional
+
+
+def run(
+    string: str,
+    string_enum: Literal["foo", "bar"],
+    boolean: bool,
+    integer: int,
+    number: float,
+    array: List[str],
+    string_optional: Optional[str] = None,
+    integer_with_default: int = 42,
+    boolean_with_default: bool = True,
+    number_with_default: float = 3.14,
+    string_with_default: str = "hello",
+    array_optional: Optional[List[str]] = None,
+):
+    """Demonstrates all supported Python parameter types and variations.
+    Args:
+        string: A required string property
+        string_enum: A required string property constrained to specific values
+        boolean: A required boolean property
+        integer: A required integer property
+        number: A required number (float) property
+        array: A required string array property
+        string_optional: An optional string property (Optional[str] with None default)
+        integer_with_default: An optional integer with a non-None default value
+        boolean_with_default: An optional boolean with a default value
+        number_with_default: An optional number with a default value
+        string_with_default: An optional string with a default value
+        array_optional: An optional string array property
+    """
+    output = f"""string: {string}
+string_enum: {string_enum}
+boolean: {boolean}
+integer: {integer}
+number: {number}
+array: {array}
+string_optional: {string_optional}
+integer_with_default: {integer_with_default}
+boolean_with_default: {boolean_with_default}
+number_with_default: {number_with_default}
+string_with_default: {string_with_default}
+array_optional: {array_optional}"""
+
+    for key, value in os.environ.items():
+        if key.startswith("LLM_"):
+            output = f"{output}\n{key}: {value}"
+
+    return output

assets/functions/tools/demo_sh.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Demonstrate how to create a tool using Bash and how to use comment tags.
+# @option --string!                  Define a required string property
+# @option --string-enum![foo|bar]    Define a required string property with enum
+# @option --string-optional          Define a optional string property
+# @flag --boolean                    Define a boolean property
+# @option --integer! <INT>           Define a required integer property
+# @option --number! <NUM>            Define a required number property
+# @option --array+ <VALUE>           Define a required string array property
+# @option --array-optional*          Define a optional string array property
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC2154
+main() {
+    cat <<EOF >> "$LLM_OUTPUT"
+string: ${argc_string}
+string_enum: ${argc_string_enum}
+string_optional: ${argc_string_optional}
+boolean: ${argc_boolean}
+integer: ${argc_integer}
+number: ${argc_number}
+array: ${argc_array[@]}
+array_optional: ${argc_array_optional[@]}
+$(printenv | grep '^LLM_')
+EOF
+}

assets/functions/tools/demo_ts.ts

@@ -0,0 +1,53 @@
+/**
+ * Demonstrates all supported TypeScript parameter types and variations.
+ *
+ * @param string - A required string property
+ * @param string_enum - A required string property constrained to specific values
+ * @param boolean - A required boolean property
+ * @param number - A required number property
+ * @param array_bracket - A required string array using bracket syntax
+ * @param array_generic - A required string array using generic syntax
+ * @param string_optional - An optional string using the question mark syntax
+ * @param string_nullable - An optional string using the union-with-null syntax
+ * @param number_with_default - An optional number with a default value
+ * @param boolean_with_default - An optional boolean with a default value
+ * @param string_with_default - An optional string with a default value
+ * @param array_optional - An optional string array using the question mark syntax
+ */
+export function run(
+  string: string,
+  string_enum: "foo" | "bar",
+  boolean: boolean,
+  number: number,
+  array_bracket: string[],
+  array_generic: Array<string>,
+  string_optional?: string,
+  string_nullable: string | null = null,
+  number_with_default: number = 42,
+  boolean_with_default: boolean = true,
+  string_with_default: string = "hello",
+  array_optional?: string[],
+): string {
+  const parts = [
+    `string: ${string}`,
+    `string_enum: ${string_enum}`,
+    `boolean: ${boolean}`,
+    `number: ${number}`,
+    `array_bracket: ${JSON.stringify(array_bracket)}`,
+    `array_generic: ${JSON.stringify(array_generic)}`,
+    `string_optional: ${string_optional}`,
+    `string_nullable: ${string_nullable}`,
+    `number_with_default: ${number_with_default}`,
+    `boolean_with_default: ${boolean_with_default}`,
+    `string_with_default: ${string_with_default}`,
+    `array_optional: ${JSON.stringify(array_optional)}`,
+  ];
+
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key.startsWith("LLM_")) {
+      parts.push(`${key}: ${value}`);
+    }
+  }
+
+  return parts.join("\n");
+}

assets/functions/tools/execute_command.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Execute the shell command.
+# @option --command! The command to execute.
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+
+main() {
+    guard_operation
+    # shellcheck disable=SC2154
+    eval "$argc_command" >> "$LLM_OUTPUT"
+}

assets/functions/tools/execute_py_code.py

@@ -0,0 +1,33 @@
+import ast
+import io
+from contextlib import redirect_stdout
+
+
+def run(code: str):
+    """Execute the given Python code.
+    Args:
+        code: The Python code to execute, such as `print("hello world")`
+    """
+    output = io.StringIO()
+    with redirect_stdout(output):
+        value = exec_with_return(code, {}, {})
+
+        if value is not None:
+            output.write(str(value))
+
+    return output.getvalue()
+
+
+def exec_with_return(code: str, globals: dict, locals: dict):
+    a = ast.parse(code)
+    last_expression = None
+    if a.body:
+        if isinstance(a_last := a.body[-1], ast.Expr):
+            last_expression = ast.unparse(a.body.pop())
+        elif isinstance(a_last, ast.Assign):
+            last_expression = ast.unparse(a_last.targets[0])
+        elif isinstance(a_last, (ast.AnnAssign, ast.AugAssign)):
+            last_expression = ast.unparse(a_last.target)
+    exec(ast.unparse(a), globals, locals)
+    if last_expression:
+        return eval(last_expression, globals, locals)

assets/functions/tools/execute_sql_code.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Execute sql code.
+# @option --code! The code to execute.
+
+# @meta require-tools usql
+
+# @env USQL_DSN! The database connection url. e.g. pgsql://user:pass@host:port
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+
+# shellcheck disable=SC2154
+main() {
+    if ! grep -qi '^select' <<<"$argc_code"; then
+        guard_operation ""
+    fi
+    usql -c "$argc_code" "$USQL_DSN" >> "$LLM_OUTPUT"
+}

assets/functions/tools/fetch_url_via_curl.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Extract the content from a given URL.
+# @option --url! The URL to scrape.
+
+# @meta require-tools pandoc
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC2154
+main() {
+    # span and div tags are dropped from the HTML https://pandoc.org/MANUAL.html#raw-htmltex and sed removes any inline SVG images in image tags from the Markdown content.
+    curl -fsSL "$argc_url" | \
+        pandoc -f html-native_divs-native_spans -t gfm-raw_html --wrap=none | \
+        sed -E 's/!\[[^]]*\]\([^)]*\)//g' \
+        >> "$LLM_OUTPUT"
+}

assets/functions/tools/fetch_url_via_jina.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Extract the content from a given URL.
+# @option --url! The URL to scrape.
+
+# @env JINA_API_KEY Your Jina API key
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC2154
+main() {
+    curl_args=()
+    if [[ -n "$JINA_API_KEY" ]]; then
+        curl_args+=("-H" "Authorization: Bearer $JINA_API_KEY")
+    fi
+    curl -fsSL "${curl_args[@]}" "https://r.jina.ai/$argc_url" >> "$LLM_OUTPUT"
+}

assets/functions/tools/fs_cat.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Read the contents of a file at the specified path.
+# Use this when you need to examine the contents of an existing file.
+
+# @option --path! The path of the file to read
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+main() {
+    # shellcheck disable=SC2154
+		cat "$argc_path" >> "$LLM_OUTPUT" 2>&1 || echo "No such file or path: $argc_path" >> "$LLM_OUTPUT"
+}

assets/functions/tools/fs_glob.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Find files by glob pattern. Returns matching file paths sorted by modification time.
+# Use this to discover files before reading them.
+
+# @option --pattern! The glob pattern to match files against (e.g. "**/*.rs", "src/**/*.ts", "*.yaml")
+# @option --path The directory to search in (defaults to current working directory)
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+MAX_RESULTS=100
+
+main() {
+    # shellcheck disable=SC2154
+    local glob_pattern="$argc_pattern"
+    local search_path="${argc_path:-.}"
+
+    if [[ ! -d "$search_path" ]]; then
+        echo "Error: directory not found: $search_path" >> "$LLM_OUTPUT"
+        return 1
+    fi
+
+    local results
+    if command -v fd &>/dev/null; then
+        results=$(fd --type f --glob "$glob_pattern" "$search_path" \
+            --exclude '.git' \
+            --exclude 'node_modules' \
+            --exclude 'target' \
+            --exclude 'dist' \
+            --exclude '__pycache__' \
+            --exclude 'vendor' \
+            --exclude '.build' \
+            2>/dev/null | head -n "$MAX_RESULTS") || true
+    else
+        results=$(find "$search_path" -type f -name "$glob_pattern" \
+            -not -path '*/.git/*' \
+            -not -path '*/node_modules/*' \
+            -not -path '*/target/*' \
+            -not -path '*/dist/*' \
+            -not -path '*/__pycache__/*' \
+            -not -path '*/vendor/*' \
+            -not -path '*/.build/*' \
+            2>/dev/null | head -n "$MAX_RESULTS") || true
+    fi
+
+    if [[ -z "$results" ]]; then
+        echo "No files found matching: $glob_pattern" >> "$LLM_OUTPUT"
+        return 0
+    fi
+
+    echo "$results" >> "$LLM_OUTPUT"
+
+    local count
+    count=$(echo "$results" | wc -l)
+    if [[ "$count" -ge "$MAX_RESULTS" ]]; then
+        printf "\n(Results limited to %s files. Use a more specific pattern.)\n" "$MAX_RESULTS" >> "$LLM_OUTPUT"
+    fi
+}

assets/functions/tools/fs_grep.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Search file contents using regular expressions. Returns matching file paths and lines.
+# Use this to find relevant code before reading files. Much faster than reading files to search.
+
+# @option --pattern! The regex pattern to search for in file contents
+# @option --path The directory to search in (defaults to current working directory)
+# @option --include File pattern to filter by (e.g. "*.rs", "*.{ts,tsx}", "*.py")
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+MAX_RESULTS=50
+MAX_LINE_LENGTH=2000
+
+main() {
+    # shellcheck disable=SC2154
+    local search_pattern="$argc_pattern"
+    local search_path="${argc_path:-.}"
+    local include_filter="${argc_include:-}"
+
+    if [[ ! -d "$search_path" ]]; then
+        echo "Error: directory not found: $search_path" >> "$LLM_OUTPUT"
+        return 1
+    fi
+
+    local grep_args=(-rn --color=never)
+
+    grep_args+=(
+        --exclude-dir='.git'
+        --exclude-dir='node_modules'
+        --exclude-dir='target'
+        --exclude-dir='dist'
+        --exclude-dir='build'
+        --exclude-dir='__pycache__'
+        --exclude-dir='vendor'
+        --exclude-dir='.build'
+        --exclude-dir='.next'
+        --exclude='*.min.js'
+        --exclude='*.min.css'
+        --exclude='*.map'
+        --exclude='*.lock'
+        --exclude='package-lock.json'
+    )
+
+    if [[ -n "$include_filter" ]]; then
+        grep_args+=("--include=$include_filter")
+    fi
+
+    local results
+    results=$(grep "${grep_args[@]}" -E "$search_pattern" "$search_path" 2>/dev/null | head -n "$MAX_RESULTS") || true
+
+    if [[ -z "$results" ]]; then
+        echo "No matches found for: $search_pattern" >> "$LLM_OUTPUT"
+        return 0
+    fi
+
+    echo "$results" | while IFS= read -r line; do
+        if [[ ${#line} -gt $MAX_LINE_LENGTH ]]; then
+            line="${line:0:$MAX_LINE_LENGTH}... (truncated)"
+        fi
+
+        echo "$line"
+    done >> "$LLM_OUTPUT"
+
+    local count
+    count=$(echo "$results" | wc -l)
+    if [[ "$count" -ge "$MAX_RESULTS" ]]; then
+        printf "\n(Results limited to %s matches. Narrow your search with --include or a more specific pattern.)\n" "$MAX_RESULTS" >> "$LLM_OUTPUT"
+    fi
+}

assets/functions/tools/fs_ls.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe List all files and directories at the specified path.
+
+# @option --path! The path of the directory to list
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+main() {
+    # shellcheck disable=SC2154
+    ls -1 "$argc_path" >> "$LLM_OUTPUT" 2>&1 || echo "No such path: $argc_path" >> "$LLM_OUTPUT"
+}

assets/functions/tools/fs_mkdir.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Create a new directory at the specified path.
+
+# @option --path! The path of the directory to create
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+main() {
+    # shellcheck disable=SC2154
+    mkdir -p "$argc_path"
+    echo "Directory created: $argc_path" >> "$LLM_OUTPUT"
+}

assets/functions/tools/fs_patch.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Apply a patch to a file at the specified path.
+# This can be used to edit a file without having to rewrite the whole file.
+
+# @option --path! The path of the file to apply the patch to
+# @option --contents! The patch to apply to the file
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+
+# shellcheck disable=SC2154
+main() {
+    if [[ ! -f "$argc_path" ]]; then
+        error "Unable to find the specified file: $argc_path"
+        exit 1
+    fi
+
+    new_contents="$(patch_file "$argc_path" <(printf "%s" "$argc_contents"))"
+    printf "%s" "$new_contents" | git diff --no-index "$argc_path" - || true
+
+    guard_operation "Apply changes?"
+
+    printf "%s" "$new_contents" > "$argc_path"
+
+    info "Applied the patch to: $argc_path" >> "$LLM_OUTPUT"
+}

assets/functions/tools/fs_read.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Read a file with line numbers, offset, and limit. For directories, lists entries.
+# Prefer this over fs_cat for controlled reading. Use offset/limit to read specific sections.
+# Use the grep tool to find specific content before reading, then read with offset to target the relevant section.
+
+# @option --path! The absolute path to the file or directory to read
+# @option --offset The line number to start reading from (1-indexed, default: 1)
+# @option --limit The maximum number of lines to read (default: 2000)
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+MAX_LINE_LENGTH=2000
+MAX_BYTES=51200
+
+main() {
+    # shellcheck disable=SC2154
+    local target="$argc_path"
+    local offset="${argc_offset:-1}"
+    local limit="${argc_limit:-2000}"
+
+    if [[ ! -e "$target" ]]; then
+        echo "Error: path not found: $target" >> "$LLM_OUTPUT"
+        return 1
+    fi
+
+    if [[ -d "$target" ]]; then
+        ls -1 "$target" >> "$LLM_OUTPUT" 2>&1
+        return 0
+    fi
+
+    local total_lines file_bytes
+    total_lines=$(wc -l < "$target" 2>/dev/null || echo 0)
+    file_bytes=$(wc -c < "$target" 2>/dev/null || echo 0)
+
+    if [[ "$file_bytes" -gt "$MAX_BYTES" ]] && [[ "$offset" -eq 1 ]] && [[ "$limit" -ge 2000 ]]; then
+        {
+            echo "Warning: Large file (${file_bytes} bytes, ${total_lines} lines). Showing first ${limit} lines."
+            echo "Use --offset and --limit to read specific sections, or use the grep tool to find relevant lines first."
+            echo ""
+        } >> "$LLM_OUTPUT"
+    fi
+
+    local end_line=$((offset + limit - 1))
+
+    sed -n "${offset},${end_line}p" "$target" 2>/dev/null | {
+        local line_num=$offset
+        while IFS= read -r line; do
+            if [[ ${#line} -gt $MAX_LINE_LENGTH ]]; then
+                line="${line:0:$MAX_LINE_LENGTH}... (truncated)"
+            fi
+            printf "%d: %s\n" "$line_num" "$line"
+            line_num=$((line_num + 1))
+        done
+    } >> "$LLM_OUTPUT"
+
+    if [[ "$end_line" -lt "$total_lines" ]]; then
+        echo "" >> "$LLM_OUTPUT"
+        echo "(${total_lines} total lines. Use --offset $((end_line + 1)) to read more.)" >> "$LLM_OUTPUT"
+    fi
+}

assets/functions/tools/fs_rm.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Remove the file or directory at the specified path.
+
+# @option --path! The path of the file or directory to remove
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+
+# shellcheck disable=SC2154
+main() {
+    if [[ -f "$argc_path" ]]; then
+        guard_path "$argc_path" "Remove '$argc_path'?"
+        rm -rf "$argc_path"
+    fi
+
+    echo "Path removed: $argc_path" >> "$LLM_OUTPUT"
+}

assets/functions/tools/fs_write.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Write the full file contents to a file at the specified path.
+
+# @option --path! The path of the file to write to
+# @option --contents! The full contents to write to the file
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC1090
+source "$LLM_PROMPT_UTILS_FILE"
+
+# shellcheck disable=SC2154
+main() {
+    if [[ -f "$argc_path" ]]; then
+        printf "%s" "$argc_contents" | git diff --no-index "$argc_path" - || true
+        guard_operation "Apply changes?"
+    else
+        guard_path "$argc_path" "Write '$argc_path'?"
+        mkdir -p "$(dirname "$argc_path")"
+    fi
+
+    printf "%s" "$argc_contents" > "$argc_path"
+    echo "The File contents were written to: $argc_path" >> "$LLM_OUTPUT"
+}

assets/functions/tools/get_current_time.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Get the current time.
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+main() {
+    date >> "$LLM_OUTPUT"
+}

assets/functions/tools/get_current_weather.py

@@ -0,0 +1,35 @@
+import os
+from pathlib import Path
+from typing import Optional
+from urllib.parse import quote_plus
+from urllib.request import urlopen
+
+
+def run(
+    location: str,
+    llm_output: Optional[str] = None,
+) -> str:
+    """Get the current weather in a given location
+
+    Args:
+        location (str): The city and optionally the state or country (e.g., "London", "San Francisco, CA").
+
+    Returns:
+        str: A single-line formatted weather string from wttr.in (``format=4`` with metric units).
+    """
+    url = f"https://wttr.in/{quote_plus(location)}?format=4&M"
+
+    with urlopen(url, timeout=10) as resp:
+        weather = resp.read().decode("utf-8", errors="replace")
+
+    dest = llm_output if llm_output is not None else os.environ.get("LLM_OUTPUT", "/dev/stdout")
+
+    if dest not in {"-", "/dev/stdout"}:
+        path = Path(dest)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("a", encoding="utf-8") as fh:
+            fh.write(weather)
+    else:
+        pass
+
+    return weather

assets/functions/tools/get_current_weather.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Get the current weather in a given location.
+# @option --location! The city and optionally the state or country, e.g., "London", "San Francisco, CA".
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+main() {
+    curl -fsSL "https://wttr.in/$(echo "$argc_location" | sed 's/ /+/g')?format=4&M" \
+    >> "$LLM_OUTPUT"
+}

assets/functions/tools/get_current_weather.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env tsx
+
+import { appendFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+
+/**
+ * Get the current weather in a given location
+ * @param location - The city and optionally the state or country (e.g., "London", "San Francisco, CA").
+ */
+export async function run(location: string): string {
+  const encoded = encodeURIComponent(location);
+  const url = `https://wttr.in/${encoded}?format=4`;
+
+  const resp = await fetch(url);
+  const data = await resp.text();
+
+  const dest = process.env["LLM_OUTPUT"] ?? "/dev/stdout";
+  if (dest !== "-" && dest !== "/dev/stdout") {
+    mkdirSync(dirname(dest), { recursive: true });
+    appendFileSync(dest, data, "utf-8");
+  }
+
+  return data;
+}

assets/functions/tools/search_arxiv.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Search arXiv using the given search query and return the top papers.
+
+# @option --query! The search query.
+
+# @env ARXIV_MAX_RESULTS=3 The max results to return.
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+main() {
+    # shellcheck disable=SC2154
+    encoded_query="$(jq -nr --arg q "$argc_query" '$q|@uri')"
+    url="http://export.arxiv.org/api/query?search_query=all:$encoded_query&max_results=$ARXIV_MAX_RESULTS"
+    curl -fsSL "$url" >> "$LLM_OUTPUT"
+}

assets/functions/tools/search_wikipedia.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Search Wikipedia using the given search query.
+# Use it to get detailed information about a public figure, interpretation of a complex scientific concept or in-depth connectivity of a significant historical event, etc.
+
+# @option --query! The search query.
+
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC2154
+main() {
+    encoded_query="$(jq -nr --arg q "$argc_query" '$q|@uri')"
+    base_url="https://en.wikipedia.org/w/api.php"
+    url="$base_url?action=query&list=search&srprop=&srlimit=1&limit=1&srsearch=$encoded_query&srinfo=suggestion&format=json"
+    json="$(curl -fsSL "$url")"
+    # suggestion="$(echo "$json" | jq -r '.query.searchinfo.suggestion // empty')"
+    title="$(echo "$json" | jq -r '.query.search[0].title // empty')"
+    pageid="$(echo "$json" | jq -r '.query.search[0].pageid // empty')"
+
+    if [[ -z "$title" || -z "$pageid" ]]; then
+        echo "error: no results for '$argc_query'" >&2
+        exit 1
+    fi
+
+    title="$(echo "$title" | tr ' ' '_')"
+    url="$base_url?action=query&prop=extracts&explaintext=&titles=$title&exintro=&format=json"
+    curl -fsSL "$url" | jq -r '.query.pages["'"$pageid"'"].extract' >> "$LLM_OUTPUT"
+}

assets/functions/tools/search_wolframalpha.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Get an answer to a question using Wolfram Alpha. The input query should be in English.
+# Use it to answer user questions that require computation, detailed facts, data analysis, or complex queries.
+
+# @option --query! The search/computation query to pass to Wolfram Alpha
+
+# @env WOLFRAM_API_ID! Your Wolfram Alpha API ID
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC2154
+main() {
+    encoded_query="$(jq -nr --arg q "$argc_query" '$q|@uri')"
+    url="https://api.wolframalpha.com/v2/query?appid=${WOLFRAM_API_ID}&input=$encoded_query&output=json&format=plaintext"
+
+    curl -fsSL "$url" | jq '[.queryresult | .pods[] | {title:.title, values:[.subpods[].plaintext | select(. != "")]}]' \
+    >> "$LLM_OUTPUT"
+}

assets/functions/tools/send_mail.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Send an email.
+# @option --recipient! The recipient of the email.
+# @option --subject! The subject of the email.
+# @option --body! The body of the email.
+
+# @env EMAIL_SMTP_ADDR! The SMTP Address, e.g. smtps://smtp.gmail.com:465
+# @env EMAIL_SMTP_USER! The SMTP User, e.g. alice@gmail.com
+# @env EMAIL_SMTP_PASS! The SMTP Password
+# @env EMAIL_SENDER_NAME The sender's name
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC2154
+main() {
+    sender_name="${EMAIL_SENDER_NAME:-$(echo "$EMAIL_SMTP_USER" | awk -F'@' '{print $1}')}"
+    printf "%s\n" "From: $sender_name <$EMAIL_SMTP_USER>
+To: $argc_recipient 
+Subject: $argc_subject
+
+$argc_body" | \
+    curl -fsS --ssl-reqd \
+        --url "$EMAIL_SMTP_ADDR" \
+        --user "$EMAIL_SMTP_USER:$EMAIL_SMTP_PASS" \
+        --mail-from "$EMAIL_SMTP_USER" \
+        --mail-rcpt "$argc_recipient" \
+        --upload-file -
+    echo "Email sent successfully" >> "$LLM_OUTPUT"
+}

assets/functions/tools/send_twilio.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Send SMS or Twilio Messaging Channels messages using the Twilio API.
+# @option --to-number! The recipient's phone number. Prefix it with 'whatsapp:' for WhatsApp messages, e.g. whatsapp:+1234567890
+# @option --message! The content of the message to be sent
+
+# @env TWILIO_ACCOUNT_SID! The twilio account sid
+# @env TWILIO_AUTH_TOKEN! The twilio auth token
+# @env TWILIO_FROM_NUMBER! The twilio from number
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC2154
+main() {
+    from_number="$TWILIO_FROM_NUMBER"
+    to_number="$argc_to_number"
+
+    if [[ "$to_number" == 'whatsapp:'* ]]; then
+        from_number="whatsapp:$from_number"
+    fi
+
+    if [[ "$to_number" != 'whatsapp:'* && "$to_number" != '+'*  ]]; then
+        to_number="+$to_number"
+    fi
+
+    res="$(curl -s -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Messages.json" \
+        -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
+        -w "\n%{http_code}" \
+        --data-urlencode "From=$from_number" \
+        --data-urlencode "To=$to_number" \
+        --data-urlencode "Body=$argc_message")"
+    status="$(echo "$res" | tail -n 1)"
+    body="$(echo "$res" | head -n -1)"
+
+    if [[ "$status" -ge 200 && "$status" -lt 300 ]]; then
+        if [[ "$(echo "$body" | jq -r 'has("sid")')" == "true" ]]; then
+            echo "Message sent successfully" >> "$LLM_OUTPUT"
+        else
+            _die "error: $body"
+        fi
+    else
+        _die "error: $body"
+    fi
+}
+
+_die() {
+    echo "$*" >&2
+    exit 1
+}
+

assets/functions/tools/web_search_loki.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -e
+
+# @describe Perform a web search to get up-to-date information or additional context.
+# Use this when you need current information or feel a search could provide a better answer.
+
+# @option --query! The search query.
+
+# @meta require-tools loki
+
+# @env WEB_SEARCH_MODEL=gemini:gemini-2.5-flash The model for web-searching.
+#
+# supported loki models:
+#   - gemini:gemini-2.0-*
+#   - vertexai:gemini-*
+#   - perplexity:*
+#   - ernie:*
+# @env LLM_OUTPUT=/dev/stdout The output path
+
+# shellcheck disable=SC2154
+main() {
+    client="${WEB_SEARCH_MODEL%%:*}"
+
+    if [[ "$client" == "gemini" ]]; then
+        export LOKI_PATCH_GEMINI_CHAT_COMPLETIONS='{".*":{"body":{"tools":[{"google_search":{}}]}}}'
+    elif [[ "$client" == "vertexai" ]]; then
+        export LOKI_PATCH_VERTEXAI_CHAT_COMPLETIONS='{
+    "gemini-1.5-.*":{"body":{"tools":[{"googleSearchRetrieval":{}}]}},
+    "gemini-2.0-.*":{"body":{"tools":[{"google_search":{}}]}}
+}'
+    elif [[ "$client" == "ernie" ]]; then
+        export LOKI_PATCH_ERNIE_CHAT_COMPLETIONS='{".*":{"body":{"web_search":{"enable":true}}}}'
+    fi
+
+    loki -m "$WEB_SEARCH_MODEL" "$argc_query" >> "$LLM_OUTPUT"
+}