Skip to main content

How Jevlin works

Jevlin is one binary. Setup teaches each coding agent to call it, the agent calls it once per search, and the router does the rest.

One binary​

The jevlin command runs when an agent or a person invokes it, answers, and exits. Everything the agent needs to know is in a skill, and everything that keeps a session's searches together is in a few small hooks. See Quickstart to install it.

What setup writes​

jevlin setup registers your installation with the search platform, stores the key it gets back in ~/.jevlin/credentials.json, and then sets up the coding agents it finds on the machine. For each one it writes two things:

  • A skill, rendered for that agent and the shell it runs on your OS. The skill tells the agent to prefer this search over its built-in one, how to build the request, how to read the answer, and what the /jevlin commands do. See Search from your agent.
  • Hooks, where the agent supports them. A hook runs before a search to put the session's identity in front of the command, and at a session's start and end to start short detached work. Hooks thread ids; they do not read your files or your prompts.

The integration pages list exactly what is written into each agent, and jevlin agents status shows what is in place.

The search path​

ON YOUR MACHINEYour agentasks a questionjevlin search --stdinthe skill builds the request;the hooks add the trace:hashed ids, scrubbed contextone requestone envelopeRouterapi.jevlin.aifans out, merges,attributes each pageWeb indexesExa, Brave, Serper, SerpAPI, Telem…Answer enginesOpenAI web search, PerplexityResearch agentsParallel, on the slow laneeleven core arms in balanced and max; one in fastrecords the searchPlatform · platform.jevlin.aiTraces: one search, a receipt per providerTrajectories: one thread as the path the agent took
  1. The agent builds one JSON request and pipes it to jevlin search --stdin. The query never touches the command line.
  2. The binary adds the stored key and a small trace, and sends one request to the router at api.jevlin.ai.
  3. The router holds the provider keys. In the balanced and max tiers it runs the query against the core providers at once; in fast it asks one.
  4. The router answers once, with everything the providers returned: a merged list deduplicated by page, each provider's own answer, which providers ran, the cost and the latency.
  5. The binary prints one JSON envelope and exits. The agent reads result.merged first and answers from it.

Search is free for agents. Setup gets the key; there is no card and nothing to top up. What funds it is described under Earning with mining.

Where things live​

Under ~/.jevlin, or the directory JEVLIN_HOME names:

pathwhat it is
jevlin.tomlThe config. Setup writes it and never rewrites it.
credentials.jsonThe search key, owner-only.
search-default, search-tierYour /jevlin on|off and /jevlin tier choices.
state/Identity, authorization and the stamps the background work leaves.
sessions/Lineage files, one per workspace, that keep a session's searches together.
bin/jevlinA native binary, and jevlin.previous after an upgrade.

Files and locks lists every file and which are safe to delete.

What the platform shows​

Setup prints a link to claim your agent on platform.jevlin.ai. Once claimed, the platform shows:

  • Traces: one search, with a receipt per provider: its status, latency, result count and cost.
  • Trajectories: one thread, an agent's session, as the path the agent took, turn by turn, with the text it wrote before each search and the pages that came back.
  • Limits: the key's spend caps and today's spend, which jevlin limits also reads.

Search works before you claim the agent; only the platform's view waits. See Trajectory observability.