janet

Simple coding assistant written entirely in bash. Janet is bootstrapped now, as part of testing janet is co-authoring itself.

Dependencies

Janet requires the following tools to be installed:

• Core utilities: sed, awk, grep, tr, nl, sort, uniq, head, tail, wc
• File operations: find, cat, ls, mv, cp, rm, mkdir, touch
• Network & hashing: curl, jq, sha256sum, diff, patch
• Optional: glow (for rendering markdown responses), firejail (for sandboxing)

Usage

./janet.sh

Initialize your first Janet config with .config create in the Janet REPL. This creates .janet/.janet.conf in the project working directory.

Requires an OpenAI-compatible API instance running (e.g., llama.cpp at http://localhost:8080). The default model is llama-tool but can be configured to use any model.

Project-Specific Instructions

Create an AGENTS.md, JANET.md, or .agents.md file in your project directory (checked in that order):

# My Project

## Architecture
- Python Django backend
- PostgreSQL database
## Coding Standards
- Use type hints
- Write tests for all new features

Janet will automatically load and use these instructions.

Task Management

For complex work, Janet can break it into focused tasks:

> Refactor the authentication system to use JWT
Janet creates tasks:
- analyze_current_auth
- implement_jwt
- add_tests
- update_docs
Then works through each systematically.

Skills System

Store project-specific knowledge in .skills/ directory. Skill files must be .md files with YAML frontmatter:

mkdir .skills
cat > .skills/python-testing.md << 'EOF'
---
name: python-testing
description: How to write tests for this project
tags: python, pytest
---
# Python Testing
## Running Tests
```bash
pytest tests/

Janet can load skills on-demand when needed using the list_skills, search_skills, and load_skill tools. Skills are loaded into the conversation context as system messages.

Shell Sessions

For long-running processes, servers, or interactive programs, Janet uses background tmux sessions to avoid blocking the main loop:

• session_start: Start a process in a new background session.
• session_logs: Capture the last N lines of output from a session.
• session_send: Send a command or key sequence to a session.
• session_stop: Terminate a background session.
• session_list: List all active Janet tmux sessions.

REPL Dot Commands

When running Janet interactively, you can use dot commands to manage the session:

Navigation & Control

• .q, .quit, .exit: Exit the session.
• .h, .help: Show all available dot commands.

Session Management

• .save [filename]: Save the current conversation history (default: timestamped file in .janet/).
• .load <filename>: Load a saved conversation history (replaces current history).
• .undo: Remove the last user message and the assistant's response.
• .clear: Clear the entire conversation history.

Inspection

• .history: Display the conversation history.
• .stats: Show token usage statistics.
• .config: Show current configuration.
• .config create: Launch the configuration wizard to create .janet/.janet.conf.
• .tools: List all available tools.

Data Management

• .wb, .whiteboard: Show the contents of the Whiteboard.
• .db, .darkboard: List all observations in the Darkboard.
• .obs <obs_id>: View a specific observation by its ID.
• .tasks: Show the status of active tasks.

Memory Systems

Janet uses two types of persistent memory to maintain context across long sessions:

• Whiteboard: A key-value store for important findings, plans, and notes. Stored in .janet/.janet_whiteboard.json.
• Darkboard: An observation log that tracks historical data and its staleness. Stored in .janet/.janet_darkboard/.

MCP Support

Janet integrates with the Model Context Protocol (MCP) to extend its toolset:

• Configuration: Define servers in .janet/mcp_servers.json.
• Initialization: Servers are automatically initialized at startup.
• Capabilities: Allows Janet to use tools provided by external MCP servers.

Configuration

Janet loads configuration from .janet/.janet.conf (project-local, priority) or ~/.janet.conf (global fallback). Use .config create in the REPL to generate a config file interactively.

API Configuration

• API_URL: The API endpoint (default: http://localhost:8080/v1/chat/completions).
• MODEL: The model name to use (default: llama-tool).
• MAX_TOKENS: Maximum response tokens (default: 230000).

Sandbox & Security

Janet supports firejail for sandboxing shell executions:

• JANET_SANDBOX=auto: Try firejail, fallback to direct execution with a warning (default).
• JANET_SANDBOX=true: Require firejail, fail if unavailable.
• JANET_SANDBOX=false: No sandboxing (less secure).
• JANET_SANDBOX_NET=false: Block network access within the sandbox (default).
• JANET_SANDBOX_NET=true: Allow network access in the sandbox (needed for pip, npm, etc.).

Shell Execution

• JANET_SHELL_INTERACTIVE=false: Capture output and return it to the LLM (default, safer).
• JANET_SHELL_INTERACTIVE=true: Show command output in real-time (can answer interactive prompts).
• JANET_MAX_SHELL_OUTPUT=10000: Maximum characters of shell output to capture.

Behavior

• JANET_AUTO_CONFIRM=true: Skip confirmation prompts for file edits.
• JANET_AUTO_CONFIRM_SHELL=true: Skip confirmation prompts for shell commands.
• JANET_USE_GLOW=false: Use glow for rendering LLM markdown responses (default: false).
• JANET_SHOW_TOKENS=true: Show token usage statistics (default: true).
• JANET_LOG_TO_SCREEN=true: Log events to stderr (default: true).
• JANET_MAX_READ_LINES=2000: Maximum lines to read in a single file read operation.