Verne

Verne is a static, client-side interface for the Google Jules API. It allows users to manage sources, sessions, and activities directly from the browser with a clean, responsive UI.

Features

• CLI Support: A powerful Python CLI (verne) to manage AI sessions, sources, agents, PRs, and automation.
• Session Management: Create, view, and manage your AI sessions.
• Source Management: Organize and manage your data sources.
• Responsive Design: Optimized for both desktop (sidebar navigation) and mobile (bottom navigation) experiences.
• PWA Support: Installable as a Progressive Web App (PWA) for a native-like experience.
• Settings & Customization: Configure notifications and other application settings.

Tech Stack

Web

• Framework: Astro, Svelte, TypeScript
• Styling: Tailwind CSS
• Testing: Playwright + Cucumber (BDD)
• Deployment: GitHub Pages

CLI

• Language: Python 3.11+
• Framework: Typer + httpx + Rich
• Package Manager: uv
• Testing: pytest-bdd (BDD with Gherkin feature files)

Getting Started

Follow these steps to set up and run Verne locally.

Prerequisites

• Node.js 22.12.0+ for the frontend (Astro 6 requirement)
• Python 3.11+ for the CLI

Web App Installation

1. Ensure Node.js version is correct:

   nvm use
   

2. Install dependencies:

   npm install
   

Web App Configuration

No .env file is needed. The web app prompts for your Google Cloud API key via the login screen at runtime. The key is stored in browser storage (localStorage or sessionStorage depending on "Remember me" preference).

For demo mode (no API key needed):

VITE_DEMO_MODE=true npm run dev

Running the Web App

Start the development server:

npm run dev

The web application will be available at http://localhost:4321/verne.

CLI Installation

Verne also includes a powerful Python CLI.

1. Install dependencies with uv:

   uv sync
   

2. Verify the installation:

   uv run verne --help
   

CLI Configuration

Authenticate with the Jules API using your Google Cloud API key:

verne auth login

Alternatively, you can set the JULES_API_KEY environment variable.

• VERNE_HTTP_TIMEOUT — HTTP timeout in seconds for Jules API calls. Default: 60.

Usage Examples (CLI)

Here are some common commands to get you started with the verne CLI:

• Check authentication status:

  verne auth status
  

• List available sources:

  verne sources list
  

• Create a new AI coding session: (Note: sessions new is the preferred command and replaces the deprecated sessions create)

  verne sessions new "Refactor auth module" --source "owner/repo"
  

  Or use a file for long prompts:

  verne sessions new --prompt-file path/to/prompt.txt --source "owner/repo"
  

• Watch a session until it completes (prints the PR link when done):

  verne sessions watch <session_id>
  

• Block and wait until a session reaches a notable state (useful for CI scripts):

  verne sessions wait <session_id> --on any
  

• List active sessions:

  verne sessions list --filter active
  

• Show session details and compact activity summary:

  verne sessions show <session_id> --activities
  

• Show full verbose session activities (with filters):

  verne sessions show <session_id> --activities --full --limit 10 --type planGenerated
  

• Find pull requests associated with a session:

  verne pr find <session_id>
  

• Run agent automation checks (merge PRs, schedule heartbeats):

  verne automate prs-merge
  verne automate schedule-heartbeat
  

Static demo build (fixtures)

• Demo mode uses bundled Jules snapshots in fixtures/jules so no API calls are made.
• Build the demo bundle (served under /verne/demo/ when published):

npm run build:demo

The output will be in dist/demo. Upload that folder alongside the normal dist build to GitHub Pages to expose https://franklinbaldo.github.io/verne/demo/.

Security & Trust Model

Verne handles your Google Cloud API key entirely client-side. The key is stored securely in your browser's localStorage (or sessionStorage if "Remember me" is unchecked).

Important: If you use the Orchestration features with cron-job.org for scheduled heartbeats, your Jules API key must be sent to the cron service to keep the sessions alive. While this is necessary for background tasks, it's recommended to create a dedicated API key with restricted permissions if you plan on using these scheduling features.

Project Structure

• src/pages/: Astro pages with file-based routing (index, sessions, sources, agents, settings).
• src/components/: Reusable Astro components (DemoBanner, EmptyState, StatusBadge, Toast, etc.).
• src/lib/: Shared TypeScript modules (auth, api-client, format, theme, types).
• src/features/: BDD feature files (Gherkin) for web and CLI.
• src/verne/: Python CLI package (Typer-based commands for auth, sessions, sources, agents).
• tests/: BDD test implementations for both web (Playwright) and CLI (pytest-bdd).
• public/: Static assets, PWA icons, and 404 fallback.
• astro.config.mjs: Astro + Vite configuration.