Skip to content

Wrappers

wrappers

Shell wrapper generation for agent CLI commands.

Produces per-provider bash functions (claude(), codex(), vibe(), etc.) that set git identity, handle session resume, and support both interactive and headless (--terok-timeout) modes.

The shell itself lives in the Jinja template resources/templates/agent-wrappers.sh.j2; this module only prepares the per-provider data the template renders. Keeping the shell in a template — rather than assembling it from Python string fragments — lets the wrapper logic be read as shell, with the vendor-specific blocks visible inline.

INITIAL_PROMPT_PATH = '/home/dev/.terok/initial-prompt.txt' module-attribute

Container path of the per-task initial prompt the TUI/CLI writes at launch.

INITIAL_PROMPT_CONSUMED_PATH = '/home/dev/.terok/initial-prompt.consumed.txt' module-attribute

Where the prompt file is moved after an agent picks it up (one-shot semantics).

INSTRUCTIONS_PATH = '/home/dev/.terok/instructions.md' module-attribute

Container path of the resolved terok per-task system instructions.

CONTAINER_WORKSPACE = '/workspace' module-attribute

Container path the host-side repo is bind-mounted at (see container/env.py).

generate_all_wrappers()

Render terok-executor.sh: a shell wrapper function for every agent.

The output file contains a shell function per agent (claude(), codex(), vibe(), …), each with correct git env vars, timeout support, and session-resume logic, plus the two shared helper functions they call. This lets interactive CLI users invoke any agent regardless of which agent was configured as default.

Source code in src/terok_executor/provider/wrappers.py 
47
48
49
50
51
52
53
54
55
56
57
def generate_all_wrappers() -> str:
    """Render ``terok-executor.sh``: a shell wrapper function for every agent.

    The output file contains a shell function per agent (``claude()``,
    ``codex()``, ``vibe()``, …), each with correct git env vars, timeout
    support, and session-resume logic, plus the two shared helper functions
    they call.  This lets interactive CLI users invoke any agent regardless of
    which agent was configured as default.
    """
    agents = [_wrapper_context(a) for a in AGENTS.values()]
    return _env().from_string(_template_source()).render(agents=agents)

generate_agent_wrapper(agent)

Render a single agent's wrapper function, without the shared helpers.

Used to inspect one agent's wrapper in isolation; the full file (with the _terok_resume_or_fresh / _terok_trust_workspace_for_vibe helpers) is produced by generate_all_wrappers.

Source code in src/terok_executor/provider/wrappers.py 
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def generate_agent_wrapper(agent: Agent) -> str:
    """Render a single agent's wrapper function, without the shared helpers.

    Used to inspect one agent's wrapper in isolation; the full file (with
    the ``_terok_resume_or_fresh`` / ``_terok_trust_workspace_for_vibe``
    helpers) is produced by
    [`generate_all_wrappers`][terok_executor.provider.wrappers.generate_all_wrappers].
    """
    ctx = _wrapper_context(agent)
    # Jinja resolves macros dynamically, so the template module's macro
    # attributes (claude_wrapper / generic_wrapper) are not statically known.
    macros: Any = _env().from_string(_template_source()).module
    if ctx["is_claude"]:
        return str(macros.claude_wrapper(ctx))
    return str(macros.generic_wrapper(ctx))