Sidekick

Sidekick is a unified assistant monorepo combining CLI, TUI, and WebUI in one installable package. This repo replaces the historical split between separate agent and webui repositories.

Quick start

Windows (PowerShell one-liner)

irm https://raw.githubusercontent.com/Loggableim/sidekick-agent/master/install.ps1 | iex

After install:

sidekick doctor           # Health check (works without API key)
sidekick dashboard        # Open WebUI at http://127.0.0.1:9119

Key facts:

⚠ Windows installer requires Administrator (UAC) by default — installs under %LOCALAPPDATA%\sidekick\
🏠 Desktop shortcut — Sidekick.lnk starts the dashboard
🌐 WebUI opens automatically in your default browser
🔄 Update by running the same command again (idempotent)
🔑 No API key required to start — configure via sidekick setup
📖 Troubleshooting — common install issues
💼 Portable mode available for no-admin installs (see below)

Ports:

Windows launcher/installer uses port 9119

CLI default is 8787 — use --port 9119 to match the launcher:

sidekick dashboard --port 9119  # Same port used by Windows launcher
sidekick dashboard              # Uses CLI default (8787)

Override with SIDEKICK_WEBUI_PORT env var or --port flag

Windows (Portable mode — no admin)

If you cannot get admin rights or prefer not to elevate, use Portable mode:

# 1. Download the installer script
Invoke-WebRequest -UseBasicParsing `
  https://raw.githubusercontent.com/Loggableim/sidekick-agent/master/install.ps1 `
  -OutFile install.ps1

# 2. Run in Portable mode (no UAC prompt)
.\install.ps1 -Mode Portable -Surface Browser -NoPrompt -SkipOptionalTools

Portable mode skips: UAC elevation, hosts alias, machine-wide env vars, optional toolchain installers. For full details see docs/troubleshooting.md.

Update / Repair

# Re-run the installer (idempotent — updates to latest version)
irm https://raw.githubusercontent.com/Loggableim/sidekick-agent/master/install.ps1 | iex

# Or if already downloaded:
.\install.ps1 -UpdateOnly

Uninstall

# Remove Sidekick (keeps ~/.sidekick config)
.\uninstall.ps1

# Remove everything including user data
.\uninstall.ps1 -RemoveUserData

macOS / Linux

git clone https://github.com/Loggableim/sidekick-agent.git
cd sidekick-agent
python -m pip install -e .
sidekick --help
sidekick doctor

Start a chat

sidekick                     # Interactive REPL
sidekick --tui               # Terminal UI mode
sidekick dashboard           # WebUI at http://127.0.0.1:9119

Legacy alias

hermes --help                # Same binary as sidekick

Screenshots

WebUI Chat / Dashboard

View	Screenshot
Dashboard — chat interface with session list and action buttons
Session — active conversation with message history
Appstore — browse and install tools/apps
Settings — theme, skin, TTS, language preferences
Agents — manage agent profiles and configurations
Skills — browse installed and available skills
Memory — memory provider status and configuration
Insights — usage analytics and session statistics
Kanban — multi-agent collaboration board
CLI Doctor — full console output	`doctor-output.txt`

`sidekick doctor` — System health check

┌─────────────────────────────────────────────────────────┐
│                 🩺 Sidekick Doctor                      │
└─────────────────────────────────────────────────────────┘

◆ Python Environment         ✓ Python 3.12.10
◆ Required Packages          ✓ OpenAI SDK  ✓ Rich  ✓ PyYAML
◆ Configuration Files        ✓ .env  ✓ config.yaml
◆ Auth Providers             ✓ OpenAI Codex  ⚠ Nous Portal

Known working: /health (200), session CRUD, workspace browsing, streaming chat, static asset serving, SSE heartbeats (5s interval), TUI import.

TUI (Terminal UI)

sidekick --tui starts the prompt_toolkit-based terminal interface. Import-verified via smoke test (19/19 green). Interactive testing requires a terminal with curses support.

Repository layout

sidekick/
├── cli/         Command-line interface (REPL, TUI, auth, config, setup)
├── runtime/     Agent runtime (providers, memory, cron, gateway, compat)
├── web/         WebUI server (48 API modules + 113 static assets)
├── shared/      Config, paths, sessions, logging, utility functions
├── tools/       ~100 tool implementations (registry, file ops, browser...)
├── docs/        Releases, roadmaps, audits, troubleshooting
├── tests/       Smoke tests and HTTP smoke checks
├── sidekick_app/  Package entrypoint with legacy-import bootstrap
└── sidekick_cli/  Legacy package forwarder (transition layer)

Commands

Command	Description
`sidekick`	Interactive chat with the agent
`sidekick doctor`	System health check
`sidekick doctor -p`	Doctor + provider connectivity check
`sidekick dashboard`	Start the WebUI (http://127.0.0.1:9119)
`sidekick setup`	Interactive setup wizard
`sidekick --tui`	Terminal UI (TUI) mode
`sidekick status`	Show component status
`sidekick model`	Select default model/provider
`sidekick login`	Authenticate with an inference provider
`sidekick cron`	Cron job management
`sidekick gateway`	Messaging gateway management
`sidekick --help`	Full command reference (38+ subcommands)

Status

Surface	Status
CLI	✅ `sidekick --help`, `sidekick`, `sidekick doctor` (exit codes 0/1/2)
TUI	✅ `sidekick --tui` (prompt_toolkit + curses, import verified)
WebUI	✅ `sidekick dashboard`, `/health`, session CRUD, SSE streaming
Runtime	✅ AIAgent (15K LOC), 76 registered tools, provider integrations
Cron	✅ Scheduler + job management
Gateway	✅ Messaging platform runner (0 import warnings)
Smoke	✅ full smoke suite plus WebUI HTTP smoke, all green
CI	✅ Linux full + macOS/Windows smoke, Python 3.12-3.14 on Linux

Configuration

Config lives under ~/.sidekick/ (or $SIDEKICK_HOME / $HERMES_HOME):

~/.sidekick/config.yaml — Settings
~/.sidekick/.env — API keys
~/.sidekick/skills/ — Installed skills
~/.sidekick/state/webui/sessions/ — Session files (JSON)
~/.sidekick/logs/ — Log files (agent.log, errors.log, gateway.log)

Home directory resolution:

$SIDEKICK_HOME → ~/.sidekick/ (canonical)
$HERMES_HOME → ~/.hermes/ (legacy fallback)
Default → ~/.sidekick/

Reference docs:

docs/architecture.md - repo and runtime architecture
docs/config-reference.md - config tree and env-var summary
docs/consolidation.md - current consolidation state and legacy naming

Graceful degradation without API key

All entry points work without any API key configured:

Command	Without API key	With API key
`sidekick --help`	✅ Full help	✅ Full help
`sidekick --version`	✅ Version info	✅ Version info
`sidekick doctor`	✅ Shows what's missing	✅ Full diagnostics
`sidekick doctor -p`	⚠ Skips provider checks	✅ Connectivity test
`sidekick dashboard`	✅ Server starts, UI loads	✅ + chat works
`sidekick`	⚠ Shows setup instructions	✅ Interactive chat

Legacy env vars preserved

HERMES_HOME, HERMES_STATE_DIR, HERMES_WEBUI_HOST, HERMES_WEBUI_PORT, HERMES_OPTIONAL_SKILLS, HERMES_LANGUAGE, HERMES_ACCEPT_HOOKS, HERMES_YOLO_MODE, HERMES_QUIET

Install from source

# Minimal (CLI only)
python -m pip install -e .

# With WebUI extras
python -m pip install -e ".[web]"

# Everything (recommended for development)
python -m pip install -e ".[all]"

Known issues

See docs/known-issues.md for the full list.

Key items:

Gateway warnings (2 non-blocking, print_config_warnings/warn_deprecated_cwd_env_vars)
Session layer: shared.sessions and web.api.models.Session still use different data models, but round-tripping now preserves WebUI-only metadata
CLI help text still references HERMES_* env vars (legacy compat — intentional)
Windows CI active (Linux full + macOS/Windows smoke)

Release history

Version	Tag	Focus
v0.1.0-monorepo	`v0.1.0-monorepo`	First monorepo baseline, all code merged
v0.2.0	`v0.2.0`	Rebrand: CLI help, localStorage, audit
v0.3.0	`v0.3.0`	Session contract, gateway warnings, CI smoke
v0.4.0	`v0.4.0`	Error handling, doctor exit codes, troubleshooting
v0.5.0	`v0.5.0`	Doctor --check-providers, macOS CI, streaming stability
v0.8.2	`v0.8.2`	Windows installer portable mode finalization
v0.8.4	`v0.8.4`	WebUI first-run onboarding fix: FastAPI routes, path detection, frontend field name
v0.8.5	`v0.8.5`	WebUI API proxy: auto-start stdlib backend, proxy all missing /api/* routes

Troubleshooting

See docs/troubleshooting.md for:

Installation / Fresh Clone
Missing API keys
Provider/Credentials
WebUI doesn't start
Sessions/State paths
Legacy HERMES_* aliases
Migration from ~/.hermes to ~/.sidekick
Logs and diagnostics
Smoke tests

Name		Name	Last commit message	Last commit date
Latest commit History 390 Commits
.codex-run-logs		.codex-run-logs
.github/workflows		.github/workflows
.playwright-cli		.playwright-cli
app/routes		app/routes
cli		cli
cron		cron
docs		docs
gateway		gateway
home/spaces/nova		home/spaces/nova
output/playwright		output/playwright
plugins/model-providers		plugins/model-providers
providers		providers
runtime		runtime
scripts		scripts
shared		shared
sidekick_app		sidekick_app
sidekick_cli		sidekick_cli
skills		skills
tests		tests
tools		tools
web		web
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG-v0.8.0.md		CHANGELOG-v0.8.0.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
None		None
README.md		README.md
SOUL.md		SOUL.md
Sidekick-Launcher.ps1		Sidekick-Launcher.ps1
_find_hermes.py		_find_hermes.py
_smoke_runtime.py		_smoke_runtime.py
_v.py		_v.py
audit-deepseek-v4-pro.md		audit-deepseek-v4-pro.md
audit-opencode-codex.md		audit-opencode-codex.md
bootstrap.py		bootstrap.py
check_ps_syntax.ps1		check_ps_syntax.ps1
diag.ps1		diag.ps1
diag2.ps1		diag2.ps1
diag3.ps1		diag3.ps1
diag4.ps1		diag4.ps1
diag5.ps1		diag5.ps1
fix_installer.py		fix_installer.py
fix_venv_paths.py		fix_venv_paths.py
install.ps1		install.ps1
launcher.bat		launcher.bat
model_tools.py		model_tools.py
patch_v074.py		patch_v074.py
pyproject.toml		pyproject.toml
reboot.bat		reboot.bat
run_agent.py		run_agent.py
shutdown.bat		shutdown.bat
sidekick.ps1		sidekick.ps1
sidekick_constants.py		sidekick_constants.py
start.ps1		start.ps1
start.sh		start.sh
state.db		state.db
test_core.ps1		test_core.ps1
test_hosts.ps1		test_hosts.ps1
test_hosts_manual.ps1		test_hosts_manual.ps1
test_integration.py		test_integration.py
test_sidekick_install.ps1		test_sidekick_install.ps1
test_sidekick_url.ps1		test_sidekick_url.ps1
test_simple.ps1		test_simple.ps1
test_try_copy.ps1		test_try_copy.ps1
toolsets.py		toolsets.py
uninstall.ps1		uninstall.ps1

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Sidekick

Quick start

Windows (PowerShell one-liner)

Windows (Portable mode — no admin)

Update / Repair

Uninstall

macOS / Linux

Start a chat

Legacy alias

Screenshots

WebUI Chat / Dashboard

`sidekick doctor` — System health check

TUI (Terminal UI)

Repository layout

Commands

Status

Configuration

Graceful degradation without API key

Legacy env vars preserved

Install from source

Known issues

Release history

Troubleshooting

About

Uh oh!

Releases 2

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Sidekick

Quick start

Windows (PowerShell one-liner)

Windows (Portable mode — no admin)

Update / Repair

Uninstall

macOS / Linux

Start a chat

Legacy alias

Screenshots

WebUI Chat / Dashboard

sidekick doctor — System health check

TUI (Terminal UI)

Repository layout

Commands

Status

Configuration

Graceful degradation without API key

Legacy env vars preserved

Install from source

Known issues

Release history

Troubleshooting

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`sidekick doctor` — System health check

Packages