Valor

Versatile Assistant for Life, Organization, and Reasoning

Valor is a local-first ambient career coach for developers. It works through your daily assistant interactions, captures meaningful work evidence, maps that work to your own career framework, and nudges you toward stronger habits over time.

Status: alpha. The current repo is a working local core for Claude Code, Codex CLI, and Cursor.

Why Valor Exists

Most career tools are either:

• manual brag docs
• manager and HR systems
• commit-only summaries

Those approaches miss a lot of real engineering work: debugging, design thinking, cross-team alignment, operational ownership, mentoring, and the drafting work that happens before anything is merged.

Valor is built around a different assumption: developers already spend a large part of their day working with assistants and agents. If that interaction layer is made useful, careful, and privacy-conscious, it can become an ambient coach that helps with both daily execution and long-term growth.

Design Principles

• Dev-first: built around real developer workflows, not generic HR forms.
• Local-first: your data lives on your machine in files you control.
• Privacy-first: no built-in telemetry, analytics, or cloud sync in this repo.
• Inspectable: most of the system is plain Markdown and Python.
• Bring your own framework: Valor adapts to your company's ladder instead of hardcoding one.

What Valor Does Today

Agent	Trigger	What it does
Morning Briefing	Auto before 11am, or /valor-briefing	Jira tickets, PRs, calendar, news, coaching, and priorities ranked by week goals + dependencies
PR Review Coach	/valor-pr-review or "help me review"	Senior-level code review guidance with architecture, testing, and tone coaching
PR Review Console	/valor-pr-console or "build a review console"	Turns a PR into an interactive C4 walkthrough (context → containers → components → real code) with Before ⇄ After, a request-flow animation, and a diff-verified mastery quiz that gates "approval-ready" on understanding
Design Doc Coach	/valor-design-doc or "how should I approach"	Structured design guidance with options, trade-offs, and recommendations
Weekly Reflection	Auto Friday, or /valor-weekly	Week summary mapped to competencies, gap analysis, and 1:1 narrative
Evening Wrap-up	Auto after 4pm, or /valor-wrapup	Day summary, carry-forward items, career reflection, and meeting-notes capture from calendar attachments
1:1 Prep	/valor-prep or "prep for 1:1"	Evidence-grounded prep, drafted in your own 1:1-doc format, with chronic blockers surfaced — plain-text, paste-ready
Project Sync Prep	/valor-sync-prep or "sync prep"	Team-facing talk points for an upcoming project sync — progress, decisions, open questions — plain-text, paste-ready
Performance Reflection	/valor-reflection or "half-year reflection"	Review-ready self-reflection draft from the cycle's evidence — impact themes mapped to competency and value (plus an AI-tier if your framework defines one), with a confirm-before-submit list — plain-text, paste-ready
Upward Feedback	/valor-upward-feedback or "feedback about my manager"	Draft feedback about your manager, grounded in observed behaviors from meeting notes + 1:1 evidence — plain-text, paste-ready
Setup	/valor-setup or "set up valor"	Guided career framework, level, and integration configuration

Beyond the discrete commands, Valor also supports ambient coaching. After a meaningful task, it can classify the work, connect it to target-level competencies, and suggest one concrete "next-level" move.

A few cross-cutting behaviors run inside those workflows. A verification gate checks carried-forward claims against their source (a PR's state, whether a doc was posted or a message sent) before any briefing or wrap-up re-asserts them — so a "still blocked, N days" note never rides on an unchecked guess. Before it plans, the briefing ranks the day's work against this week's goals — read from your 1:1 doc — and your standing dependency rules, showing the why on each priority, and surfaces spare-capacity backlog pickups when the day is light. The briefing then turns its priorities into a day plan fit to your calendar's real gaps (deep vs fragmented), sizing each task and leaving a breather after meetings, optionally written back as private calendar items that carry the task on the block and land on clean clock times. And for people who rotate between projects, an opt-in project focus plans around the project whose sync is next and hides the rest — noticing on its own when you pick up or drop a project. At day's end, the wrap-up pulls meeting notes from your calendar events' attachments into the evidence store, so 1:1 prep and weekly reflection can draw on what actually happened in the room.

Local Data Model

Valor stores its working state under ~/.valor/:

• state.json: user settings and rolling assistant state
• career_framework.md: your career ladder and company values
• evidence.sqlite: structured evidence store + artifact-verification cache
• backups/: local database backups
• carry-forward/: local wrap-up notes and next-day pickup files

Installed prompts and rules live in your assistant's local directories:

• Claude Code: ~/.claude/CLAUDE.md and ~/.claude/commands/
• Codex CLI: ~/.codex/AGENTS.md and ~/.codex/skills/
• Cursor: ~/.cursor/rules/ and ~/.cursor/skills/

The current runtime is local-first, but not fully air-gapped by itself. See PRIVACY.md for the exact trust boundary.

Privacy and Trust

This repo does not include:

• built-in telemetry
• analytics pipelines
• automatic cloud sync
• a hosted backend

Valor may still interact with external systems through the tools already configured in your assistant environment, such as:

• gh for GitHub data
• Jira or Atlassian MCP tools
• Calendar integrations
• web search when a command explicitly uses it

Important: if your host assistant sends prompts or workspace context to a hosted model provider, that behavior is governed by the host assistant and model provider, not by this repo. Valor does not override those policies.

Install

Quick install (one command):

curl -fsSL https://raw.githubusercontent.com/yihanzhu/valor/main/install.sh | bash -s -- --clone

The bootstrap script is fetched from main (it's the entry point). It's a short shell script — read it before piping to bash (curl -fsSL …/main/install.sh | less).

On first use, this clones the repo to ~/.valor/repo/, creates ~/.valor/ for local state and evidence, and installs Valor for all supported agents (Claude Code, Codex CLI, and Cursor). If that checkout already exists, the bootstrap leaves it unchanged and reinstalls the version already checked out. Valor checks daily for new releases (tagged vX.Y.Z, never main HEAD) and notifies you when one is available — updating is manual (see below). It never silently pulls main or checks anything out.

Manual install:

git clone https://github.com/yihanzhu/valor.git ~/.valor/repo
cd ~/.valor/repo
bash install.sh

Install for a specific target only:

bash install.sh --target claude-code   # Claude Code only
bash install.sh --target codex         # Codex CLI only
bash install.sh --target cursor        # Cursor only

Check for updates:

cd ~/.valor/repo && bash install.sh --upgrade   # tells you if a newer release exists (never self-updates)

Update to the latest release (manual): check out the tag and re-install:

git -C ~/.valor/repo fetch --tags && git -C ~/.valor/repo checkout vX.Y.Z && bash ~/.valor/repo/install.sh

Pin a specific version: do the checkout above, then disable the daily check so nothing nudges you off it:

# set "update_check_interval_hours": 0 in ~/.valor/state.json

For a complete walkthrough including career framework setup, level configuration, and integration options, see docs/getting-started.md.

Documentation

• Getting Started
• Integrations
• Architecture
• Privacy Model
• Roadmap

Showing Valor to someone else

examples/demo/ is a seeded, entirely fictional profile for demoing all eleven workflows without exposing your own work. It installs into a throwaway HOME, so your real ~/.valor is unreachable from the demo — the mock is in the inputs (invented tickets, PRs, calendar, evidence), while every briefing, review and reflection you show is real Valor output. Ships with a ~20-minute run-book.

HOME=~/valor-demo bash install.sh && python3 examples/demo/seed.py ~/valor-demo

See examples/demo/README.md and examples/demo/DEMO.md.

Want to see the output before installing anything? valor.sh/demo replays a recorded transcript of every workflow from that same profile, and embeds a real, fully interactive PR review console you can click through.

First-Time Setup

After install, open your agent and run /valor-setup (or say "set up valor"). The guided setup walks you through:

1. Career framework -- paste your company's career ladder (from a Google Sheet, Confluence page, or any doc) and Valor structures it automatically
2. Level selection -- pick your current and target levels
3. Integrations -- configure GitHub org, Jira projects, and disable tools you don't use

No career ladder handy? Setup offers ready-made, fully generic starting points in examples/frameworks/ — a software-engineering IC ladder, an engineering-manager ladder, and a no-formal-levels growth framework — or it can generate one from your job title. Pick one, then customize. You can re-run /valor-setup anytime to reconfigure.

When you get promoted, re-run setup or update the three level fields in ~/.valor/state.json directly.

Day plan & calendar

If calendar is enabled, the morning briefing fits your priorities to the day's real gaps (deep vs fragmented) and can write the blocks back to your calendar as private items. This is controlled by the planning block in ~/.valor/state.json:

Setting	Default	Meaning
calendar_auto_write	true	Write the day plan to your calendar. Set false for plan-only (shown in the briefing, nothing written).
workday_start / workday_end	09:00 / 18:00	Hours the plan fits within. If unset, configured at setup.
deep_min_hours	2	Minimum contiguous hours for a gap to count as a "deep" block.

Items are written private: as a Google Task per block if a task connector is available (tasks are personal by nature), otherwise as a private calendar event (visibility: private, shown free) — so the titles stay visible only to you, not to colleagues who can see your calendar.

# e.g. plan-only, 9-to-5 workday:
python3 ~/.valor/evidence_cli.py state-set planning \
  '{"calendar_auto_write": false, "workday_start": "09:00", "workday_end": "17:00", "deep_min_hours": 2}'

Calendar events Valor creates are tagged and idempotent (re-running the briefing updates rather than duplicates), and are removed once the underlying task is verified done. Valor never touches events it didn't create.

Prerequisites

Valor works best when these tools are already available in your environment:

Tool	What for	Required?
gh CLI	GitHub PR and issue data	Recommended
Jira / Atlassian integration	Ticket discovery	Recommended
Calendar integration	Meetings and schedule context	Optional

If one of these is unavailable, the affected command should skip that section and continue with the other available signals.

Usage

Automatic suggestions:

• start a conversation before 11am on a weekday for a morning briefing
• chat on Friday for a weekly reflection prompt
• chat after 4pm on a weekday for an evening wrap-up prompt

Commands:

• /valor-briefing
• /valor-pr-review
• /valor-pr-console
• /valor-design-doc
• /valor-weekly
• /valor-wrapup
• /valor-prep
• /valor-sync-prep
• /valor-reflection
• /valor-upward-feedback
• /valor-setup

Natural language also works:

• "start my day"
• "review PR #892"
• "build a review console for #892"
• "design doc for PROJ-123"
• "what did I do this week"
• "wrap up"
• "prep for 1:1"
• "sync prep"
• "set up valor"

Ambient coaching controls:

• valor quiet: suppress coaching for this conversation
• valor off: disable ambient coaching until re-enabled
• valor on: re-enable ambient coaching

Development

Runtime code is Python stdlib-only.

Development and test setup:

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements-dev.txt
python3 -m pytest -q
python3 -m compileall src tests
python3 scripts/check_version_sync.py   # version strings (manifests, website) match VERSION

If you are editing installed artifacts locally, you can verify they still match the repo source:

./install.sh --check                          # All targets (default)
./install.sh --target claude-code --check     # Claude Code only

Project Layout

valor/
├── .claude-plugin/         # Claude Code plugin manifest (discovery only)
├── .codex-plugin/          # Codex CLI plugin manifest (discovery only)
├── bin/                    # CLI wrappers (valor-evidence)
├── commands/               # User-invoked assistant commands
├── examples/               # Example career frameworks + the seeded demo profile
├── rules/                  # Always-applied Valor rule
├── skills/                 # Plugin skills (setup)
├── src/                    # Evidence CLI, career framework, utilities
├── tests/                  # Test suite
├── docs/                   # Setup, architecture, integrations, ADRs
├── website/                # Static marketing site and install entry point
├── install.sh              # Installer for Claude Code, Codex CLI, and Cursor
├── marketplace.json        # Plugin catalog
├── VERSION                 # Version (single source of truth)
└── ...                     # LICENSE, ROADMAP, CONTRIBUTING, etc.

Contributing and Security

• Contribution guide: CONTRIBUTING.md
• Privacy model: PRIVACY.md
• Community expectations: CODE_OF_CONDUCT.md
• Security reporting: SECURITY.md

License

Licensed under Apache-2.0.

The Valor name and branding are not granted by the software license.

Roadmap

See ROADMAP.md for the current public roadmap and PRODUCT_VISION.md for the longer-term local-first vision.