Jido.Code

Jido.Code is the primary product and implementation repo in this workspace. It is a Phoenix + LiveView application built on the embedded triple-store control plane and the Jido runtime, with a separate Tauri desktop packaging path.

Status today is alpha and developer-focused. The repo is real, runnable software, but it is still evolving toward the broader product shape described in the repo-local spec workspace.

Quickstart

Normal repository development uses the repo root and repository-local embedded store state.

git clone https://github.com/mikehostetler/jido_code.git
cd jido_code

asdf install
mix setup
mix server

Then open http://localhost:4100

For normal local development, leave DATABASE_URL unset. mix setup installs dependencies and builds assets. mix server is the preferred start path and prepares browser dependencies or bundles first when the current LiveVue/Vite output is missing. Desktop packaging is separate and lives in tauri/README.md.

What This Repo Contains

Jido.Code currently centers on a few concrete areas:

• a Phoenix web app with product-owned sign-in, settings, setup, and dashboard/workbench routes
• a repo-scoped conversation orchestration layer with interruptible turns, durable event history, bounded shared context, and governed work steering
• Forge, an OTP subsystem for isolated execution sessions with observable events
• GitHub integration primitives for repos, webhook deliveries, analyses, and automation-oriented workflows
• Jido-oriented command, skill, and workflow task surfaces for local operator and developer use
• a Tauri desktop packaging path that wraps the Phoenix backend as a sidecar application

The product direction is still broader than the currently finished UX. Treat this repo as a working implementation base, not a finished end-user product.

For new repo work, prefer canonical repository or managed-repository language and governed-run terms. Keep Project and WorkflowRun references confined to explicit compatibility, migration, or audit seams.

Route Orientation

The routed entry model is intentionally split:

• /welcome is the public/bootstrap and sign-in entry route
• /setup is the signed-in continuation surface while onboarding is incomplete
• /dashboard is the durable ready-state authenticated landing
• /settings/auth is the durable home for Provider Login and Git Provider Integrations

Local Development

The repo toolchain is pinned in .tool-versions for asdf. Normal day-to-day development should feel like a conventional Phoenix app:

mix setup
mix assets.setup
mix assets.build
mix frontend.verify
mix ui_reset.verify
mix server
mix test
mix onboarding.reset --keep-owner
mix onboarding.reset --full

.env.example includes the main runtime overrides. For normal repo-root development, config/runtime.exs now auto-loads ignored .env, .env.local, and .env.dev.local files during dev boot so local values like JIDO_CODE_SECRET_REF_ENCRYPTION_KEY can be set without exporting them in your shell. Shell env vars still take precedence, and the important rule is still: leave DATABASE_URL unset and use the embedded store defaults.

You may also need extra credentials depending on what you are exercising:

• ANTHROPIC_API_KEY for Claude-powered flows
• SPRITES_API_TOKEN for live Sprites-backed execution
• mail provider settings such as RESEND_API_KEY

Product record shape changes are explicit in this repo. Update the embedded store codec, ontology, and query projection together so runtime records and semantic projections stay aligned.

Source Code Graph

The repo now carries a repository-scoped semantic source-code graph capability for managed repositories.

• The stack is built from elixir_ontologies, triple_store, sparql, and rocksdb.
• The graph is repository-local, not a global service. Each workspace keeps its store under .jido_code/source_code_graph/triple_store.
• Normal lifecycle is explicit: analyze, load or refresh the canonical source_code named graph, then query it.
• Contributors touching this stack should have the normal native build toolchain available for RocksDB-backed dependencies. The repo already pins the Elixir, Erlang, Node, Rust, and Zig toolchain through .tool-versions.

Use the semantic graph when you need cross-file semantic structure:

• module and function discovery across a repository
• bounded impact tracing
• runtime pattern lookups
• repeated SPARQL-backed structural questions
• explicit planning, review, and explanation flows that opt into bounded semantic context
• governed work or evidence adoption from semantic findings after an explicit product action

Prefer ordinary file/code tools when you need:

• exact latest source text
• line-level editing context
• one-off single-file reads
• answers that should not depend on the current graph being analyzed or loaded

Keep the semantic graph as a bounded enhancement, not a hidden dependency:

• operator and workflow paths should remain legible when the graph is stale, degraded, or unavailable
• recovery stays product-owned and repo-scoped
• semantic findings only influence product behavior after explicit governed adoption into records like Observation, Assessment, WorkItem, or Evidence

Frontend Stack

jido_code has one official browser architecture: a LiveView-owned routed area shell, SaladUI-backed HEEx primitives behind app-owned wrappers, and generated shadcn-vue primitives inside bounded live_vue islands.

• Keep route ownership, auth/session boundaries, area navigation, shell status, and straightforward forms in LiveView and HEEx.
• Add or change product areas through JidoCodeWeb.Areas, the Phoenix router, and the root <Layouts.app ...> shell instead of route-local chrome.
• Use JidoCodeWeb.Components.UI for SaladUI HEEx primitives and add new wrappers there before product LiveViews depend on a new primitive.
• Mount Vue-backed regions through <.vue_surface ...> rather than raw LiveVue calls so props, streams, and emits stay product-owned.
• Keep generated shadcn-vue primitives under assets/vue/components/ui/ and register only production-mounted islands explicitly in assets/vue/index.ts.
• Treat props: and streams: as server-authored boundaries and map Vue emits back into LiveView events.
• Do not reintroduce DaisyUI dependencies, DaisyUI component classes, broad Vue auto-registration, or the old subject-tree shell.
• When changing the browser stack, run mix frontend.verify; for focused reset guardrails, run mix ui_reset.verify. Hybrid screens must degrade to product-oriented fallback messaging instead of exposing raw Vite or SSR failures to operators.

Conversation Model

Productive coding conversations are managed-repository scoped and usually attach to one canonical WorkItem.

• Use the conversation driver and sequenced event stream for conversation UX. Snapshots are for cold load, reconnect recovery, and degraded continuity, not steady-state polling.
• Treat repo detail as the canonical conversation host surface. Workbench, run detail, and dashboard should project bounded conversation supervision and route operators back into repo detail or governed work paths instead of growing their own transcript or composer state.
• Route steering through canonical work records. If a conversation narrows, redirects, or promotes work, the durable outcome should rejoin ManagedRepo and WorkItem surfaces instead of living as free-floating chat state.
• Keep runtime readiness operator-readable. Selected provider/model, workspace prerequisites, and degraded continuity should stay visible on the route-owned conversation shell while raw sequence metadata remains secondary.
• Keep short-term collaboration context bounded and explainable. Referenced files, accepted tool results, and pending clarification state should remain explicit enough to steer follow-up work without turning conversations into hidden long-term memory.

Day-To-Day Commands

mix setup               # deps and asset build
mix assets.setup        # install browser toolchain dependencies
mix assets.build        # build the Vite + SSR browser bundle
mix frontend.verify     # run browser pipeline verification plus UI reset guardrails
mix ui_reset.verify     # run focused area shell, no-DaisyUI, explicit-registry, and fallback checks
mix runtime.verify      # verify repository runtime, pod lifecycle, snapshots, and AgentWorkspace routing
mix source_graph.verify # run the repo-owned semantic graph verification suite
mix memory.verify       # verify the ontology pair, typed governed links, and repo-owned memory recovery path
mix semantic.verify     # run the full product-facing semantic graph verification suite
mix server              # preferred local start path; prepares browser deps/builds if needed
mix onboarding.reset --keep-owner # keep the bootstrap owner, clear managed repos, and rewind to signed-in /setup
mix onboarding.reset --full       # clear bootstrap users plus managed repos and return to first-run bootstrap
mix test                # run tests
mix q                   # fast merge-safe quality gate
mix quality             # fast gate plus frontend verification, doctor, and dialyzer debt surfacing
mix precommit           # compile, format, and test
mix coveralls           # run tests with coverage summary
mix coveralls.html      # generate the HTML coverage report
mix docs                # build ExDoc output from the repo docs surface

Repo-owned CLI surfaces stay Mix-first:

mix skill.list
mix skill.run my-skill --route my/route --data '{"key":"value"}'

mix command list
mix command my-command --params '{"key":"value"}'

mix workflow.control definitions
mix workflow.run my_workflow --inputs '{"file_path":"lib/example.ex","mode":"full"}'

Repo Guides

The canonical repo-facing guides now live here:

• docs/developer/README.md for the numbered developer architecture guide set
• CONTRIBUTING.md for contributor setup and quality expectations
• memory_ontology_guide.md for the developer-facing explanation of the coding memory ontology
• tauri/README.md for the separate desktop packaging/runtime path
• CHANGELOG.md for release history
• AGENTS.md for local agent operating guidance in this repo

Semantic Memory

The repository semantic stack is now three linked named graphs in one repository-local store:

• source_code for repository structure and semantic code entities
• workflow_provenance for bounded work sessions, agent runs, tool use, plans, patches, and reviews
• memory for durable adopted facts, decisions, conventions, issues, lessons, and patterns

The write seam is explicit:

• workflow provenance is inserted at AgentWorkspace and product workflow boundaries through typed capture envelopes
• durable memory is inserted only after explicit classification or governed adoption
• raw runtime or model output is not durable memory on its own

The verification and cutover seam is explicit too:

• mix memory.verify checks the companion ontology pair, typed governed-link adoption, repository-local graph coherence, and bounded rebuild or revalidation behavior
• new memory and provenance code should emit typed governed_references directly; generic artifact-style governed links are legacy recovery-only state, not the contract for new work
• governed truth still lives in embedded product records such as ManagedRepo, WorkItem, Run, Evidence, and governed Decision; the semantic graphs store supporting recall, provenance, and cross-links

When touching the memory graph boundary, capture envelopes, memory actions, memory workspace entrypoints, or provenance or durable-memory adoption flows, run mix memory.verify.

For operational guidance on configuration, troubleshooting, and production deployment of the memory graph capability, see the Memory Graph Operations Guide.

Repo Shape

assets/   frontend assets
config/   Phoenix, embedded store, and runtime configuration
deploy/   container and deploy helper files
lib/      application and web code
priv/     static assets
tauri/    desktop packaging app
test/     tests and support code
.planning/ phased implementation and migration plans

Main Technologies

Package	Role
phoenix	Web framework and router
phoenix_live_view	Interactive server-rendered UI
triple_store	Embedded RDF-backed product store
sparql	Query layer for embedded product and semantic projections
jido	Agent runtime, signals, and orchestration patterns
req	HTTP client
burrito	Phoenix desktop sidecar packaging
tauri	Native desktop shell

Release Notes

Release automation is version-controlled in .github/workflows/release.yml. Keep CHANGELOG.md current, run the relevant quality and spec checks, and cut releases from the workflow instead of relying on ad hoc local release steps.

License

Apache-2.0 — see LICENSE for details.