Environment Plugin

Query execution environment (OS, shell, architecture) and internal context (token usage, GC thresholds) to generate platform-appropriate commands and manage resources.

Name environment
Type Tool Plugin (Registry-managed)
Auto-approved Yes (read-only, no side effects)
Tools get_environment

Use Cases

  • Shell command generation - Determine correct syntax (bash vs PowerShell)
  • Path construction - Use correct separators (/ vs \)
  • Tool availability - Know which utilities exist on the platform
  • Binary selection - Choose correct architecture (x86_64 vs arm64)
  • Context management - Monitor token usage and proactively manage context

get_environment

Query environment information with optional aspect filtering.

Parameters

Parameter Type Required Description
aspect string No Filter to specific aspect: os, shell, arch, cwd, context, or all (default)

Aspect Details

OS (aspect="os")

FieldDescriptionExamples
typeLowercase OS identifierlinux, darwin, windows
namePlatform nameLinux, Darwin, Windows
releaseOS version5.15.0, 22.1.0
friendly_nameHuman-readableLinux, macOS, Windows

Shell (aspect="shell")

FieldDescriptionExamples
defaultDefault shellbash, zsh, cmd
currentCurrent shellbash, powershell
pathShell path (Unix)/bin/bash
path_separatorPATH delimiter: (Unix), ; (Windows)
dir_separatorDirectory separator/ (Unix), \ (Windows)

Architecture (aspect="arch")

FieldDescriptionExamples
machineRaw machine typex86_64, arm64
processorProcessor infox86_64, arm
normalizedStandardized namex86_64, arm64, x86

Working Directory (aspect="cwd")

Returns the absolute path to the current working directory as a string.

Context (aspect="context")

Returns token usage and GC settings. Requires session injection via set_session_plugin().

FieldDescriptionExamples
modelModel nameclaude-sonnet-4-20250514
context_limitMax context size1048576
total_tokensTotal tokens used15234
prompt_tokensInput tokens12000
output_tokensOutput tokens3234
tokens_remainingAvailable tokens1033342
percent_usedUsage percentage1.45
turnsConversation turns5
gcGC settingsObject with thresholds

Configuration

This plugin requires no configuration for basic aspects. For context aspect, inject the session via set_session_plugin().

Basic usage
from jaato import PluginRegistry

registry = PluginRegistry()
registry.discover()
registry.expose_tool("environment")

# Get all executors
executors = registry.get_exposed_executors()

# Query all environment info
result = executors["get_environment"]({})

# Query specific aspect
os_info = executors["get_environment"]({"aspect": "os"})
shell_info = executors["get_environment"]({"aspect": "shell"})
Response: context aspect
{
  "model": "claude-sonnet-4-20250514",
  "context_limit": 1048576,
  "total_tokens": 15234,
  "prompt_tokens": 12000,
  "output_tokens": 3234,
  "tokens_remaining": 1033342,
  "percent_used": 1.45,
  "turns": 5,
  "gc": {
    "threshold_percent": 80.0,
    "auto_trigger": true,
    "preserve_recent_turns": 5
  }
}
Response: single aspect
// get_environment(aspect="shell")
{
  "default": "bash",
  "current": "bash",
  "path": "/bin/bash",
  "path_separator": ":",
  "dir_separator": "/"
}

// get_environment(aspect="cwd")
"/home/user/project"
With JaatoClient
from jaato import JaatoClient, PluginRegistry

client = JaatoClient()
client.connect()  # Reads JAATO_PROVIDER and MODEL_NAME from env

registry = PluginRegistry()
registry.discover()
registry.expose_tool("environment")
registry.expose_tool("cli")  # Often used together

client.configure_tools(registry)

# Model can now query environment before
# generating platform-specific commands
response = client.send_message(
    "List files in the current directory"
)