aradotso Elephant Agent Personal AI Skill
Skill by ara.so — AI Agent Skills collection.
Elephant Agent is a Personal-Model First Self Evolving AI Agent that starts from understanding the person, not the task. It builds a correctable Personal Model across four lenses (Identity, World, Pulse, Journey) and helps design living Paths for work, health, habits, learning, and other long-running directions.
What Elephant Agent Does
- Personal Model: Builds understanding of who you are (Identity), what surrounds you (World), what's alive right now (Pulse), and what your path has taught (Journey)
- Paths: Long-running arcs that break down into Steps with Checkpoints for human judgment
- Herd Management: Coordinates Mother elephant and baby elephants under one understanding
- Skills & Tools: Extensible system for browser, filesystem, MCP, and operator actions
- Multi-Surface: Native macOS app + CLI + Dashboard for different workflows
Installation
macOS Desktop App (Recommended)
# Download from GitHub releases
curl -L -o elephant-agent.dmg https://github.com/agentic-in/elephant-agent/releases/latest/download/Elephant-Agent.dmg
# Or visit releases page
open https://github.com/agentic-in/elephant-agent/releases/latest
CLI + Dashboard (Linux/Cloud/SSH)
# Install via install script
curl -fsSL https://elephant.agentic-in.ai/install.sh | bash
# Or manual installation
git clone https://github.com/agentic-in/elephant-agent.git
cd elephant-agent
pip install -e .
Key CLI Commands
Initialization and Setup
# Initialize Elephant Agent (first run)
elephant init
# Check system readiness
elephant status
# Configure provider settings
elephant config set provider openai
elephant config set model gpt-4
elephant config set curiosity_effort medium
# List all configuration
elephant config list
Daily Interaction
# Enter the chat TUI (main interaction mode)
elephant wake
# Quick query without entering TUI
elephant ask "What should I focus on today?"
# View Personal Model
elephant model show
# View specific model lens
elephant model show --lens identity
elephant model show --lens world
elephant model show --lens pulse
elephant model show --lens journey
Paths Management
# List all paths
elephant paths list
# Create a new path
elephant paths create "Launch new product feature"
# View path details
elephant paths show <path-id>
# Update path status
elephant paths update <path-id> --status active
# Archive completed path
elephant paths archive <path-id>
Herd Management
# List all agents in herd
elephant herd list
# Create a baby elephant for specific task
elephant herd spawn --role researcher --context "market analysis"
# View agent details
elephant herd show <agent-id>
# Remove agent from herd
elephant herd remove <agent-id>
Skills and Tools
# List available skills
elephant skills list
# Enable a skill
elephant skills enable filesystem
# Disable a skill
elephant skills disable browser
# View skill documentation
elephant skills info filesystem
Dashboard
# Open dashboard in browser
elephant dashboard
# Run dashboard without opening browser (for remote/SSH)
elephant dashboard --no-open
# Dashboard on custom port
elephant dashboard --port 8080
Configuration
Provider Configuration
# OpenAI
elephant config set provider openai
export OPENAI_API_KEY=your-key-here
# Anthropic
elephant config set provider anthropic
export ANTHROPIC_API_KEY=your-key-here
# Local models (Ollama)
elephant config set provider ollama
elephant config set model llama2
Configuration File
Elephant Agent stores configuration in ~/.elephant/config.yaml:
# ~/.elephant/config.yaml
provider: openai
model: gpt-4
curiosity_effort: medium # low, medium, high
language: en
boundaries:
- respect_privacy
- ask_before_destructive
- explain_reasoning
posture: collaborative # directive, collaborative, suggestive
Environment Variables
# Provider API keys
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export DEEPSEEK_API_KEY=...
# Elephant-specific settings
export ELEPHANT_HOME=~/.elephant
export ELEPHANT_LOG_LEVEL=info
export ELEPHANT_DASHBOARD_PORT=3000
Python API Usage
Basic Interaction
from elephant_agent import ElephantAgent, PersonalModel
# Initialize agent
agent = ElephantAgent(
provider="openai",
model="gpt-4",
curiosity_effort="medium"
)
# Load or create Personal Model
model = agent.get_personal_model()
# Ask a question
response = agent.ask("What should I prioritize today?")
print(response.message)
print(f"Confidence: {response.confidence}")
Working with Personal Model
from elephant_agent import PersonalModel
# Access model lenses
model = PersonalModel.load()
# View identity
identity = model.get_lens("identity")
print(f"Values: {identity.values}")
print(f"Decision style: {identity.decision_style}")
# Update world lens
model.update_lens("world", {
"people": ["Alice (mentor)", "Bob (colleague)"],
"projects": ["Product launch", "Team onboarding"],
"tools": ["VS Code", "Linear", "Slack"]
})
# Check pulse
pulse = model.get_lens("pulse")
print(f"Current focus: {pulse.focus}")
print(f"Energy level: {pulse.energy}")
print(f"Constraints: {pulse.constraints}")
# Save changes
model.save()
Creating and Managing Paths
from elephant_agent import Path, Step
# Create a new path
path = Path.create(
title="Launch API v2",
description="Ship new API with auth and webhooks",
context=model
)
# Add steps
path.add_step(Step(
title="Design API schema",
description="Define endpoints, auth flow, webhook events",
checkpoint=True # Requires human review
))
path.add_step(Step(
title="Implement core endpoints",
description="Build CRUD operations with auth",
checkpoint=False
))
# Start the path
path.start()
# Get next step
next_step = path.get_next_step()
print(f"Next: {next_step.title}")
# Mark step complete
path.complete_step(next_step.id)
# Save path
path.save()
Working with the Herd
from elephant_agent import Herd, BabyElephant
# Get the herd
herd = Herd.load()
# Spawn a baby elephant for a specific task
researcher = BabyElephant(
role="researcher",
context={
"focus": "competitor analysis",
"constraints": ["public data only"],
"reporting_to": "mother"
}
)
herd.add(researcher)
# Assign task to baby
task = researcher.assign_task(
"Research top 3 competitors' API offerings"
)
# Check status
status = researcher.get_status()
print(f"Progress: {status.progress}%")
# Get results
if task.is_complete():
results = task.get_results()
print(results.summary)
Skills Integration
from elephant_agent.skills import FileSystemSkill, BrowserSkill
# Initialize skills
fs_skill = FileSystemSkill(
allowed_paths=["/home/user/projects"],
readonly=False
)
browser_skill = BrowserSkill(
headless=True,
timeout=30
)
# Register skills with agent
agent.register_skill(fs_skill)
agent.register_skill(browser_skill)
# Use skills in context
response = agent.ask(
"Read the README.md and create a summary document",
skills=["filesystem"]
)
Advanced: Custom Skills
from elephant_agent.skills import Skill, SkillParameter
class GitSkill(Skill):
name = "git"
description = "Execute git commands safely"
parameters = [
SkillParameter("command", str, "Git command to run"),
SkillParameter("args", list, "Command arguments", required=False)
]
def execute(self, command: str, args: list = None):
"""Execute git command with safety checks."""
import subprocess
# Safety: only allow read operations
safe_commands = ["status", "log", "diff", "branch"]
if command not in safe_commands:
return {
"success": False,
"error": f"Command '{command}' not allowed"
}
cmd = ["git", command] + (args or [])
result = subprocess.run(
cmd,
capture_output=True,
text=True
)
return {
"success": result.returncode == 0,
"output": result.stdout,
"error": result.stderr
}
# Register custom skill
git_skill = GitSkill()
agent.register_skill(git_skill)
Common Patterns
Daily Check-in Pattern
from elephant_agent import ElephantAgent
from datetime import datetime
agent = ElephantAgent.load()
# Morning routine
def morning_checkin():
model = agent.get_personal_model()
# Update pulse
model.update_pulse({
"timestamp": datetime.now(),
"energy": "high",
"focus": ["API launch", "team sync"],
"constraints": ["3hr meeting block 2-5pm"]
})
# Get prioritized guidance
guidance = agent.ask(
"Given my current pulse and active paths, what should I prioritize today?"
)
return guidance
checkin = morning_checkin()
print(checkin.message)
Path Progress Review
from elephant_agent import Path
def review_active_paths():
paths = Path.list(status="active")
for path in paths:
print(f"\n=== {path.title} ===")
print(f"Progress: {path.progress}%")
next_step = path.get_next_step()
if next_step:
print(f"Next: {next_step.title}")
if next_step.checkpoint:
print("⚠️ Requires your review")
blockers = path.get_blockers()
if blockers:
print(f"Blockers: {', '.join(blockers)}")
Correcting the Personal Model
from elephant_agent import PersonalModel
model = PersonalModel.load()
# Correct a misunderstanding
correction = model.correct(
lens="identity",
field="values",
current="achievement, efficiency",
corrected="learning, collaboration, impact",
reason="I value learning and collaboration over pure efficiency"
)
# The model learns from corrections
print(f"Correction applied: {correction.applied}")
print(f"Impact: {correction.impact_summary}")
Integrating with Workflows
from elephant_agent import ElephantAgent
import json
agent = ElephantAgent.load()
# Export context for external tools
def export_context_for_tool(tool_name: str):
model = agent.get_personal_model()
context = {
"current_focus": model.pulse.focus,
"active_projects": model.world.projects,
"constraints": model.pulse.constraints,
"tool": tool_name
}
return json.dumps(context, indent=2)
# Import learnings back
def import_learning(source: str, content: dict):
model = agent.get_personal_model()
model.add_journey_entry({
"source": source,
"lesson": content["lesson"],
"context": content["context"],
"timestamp": content["timestamp"]
})
Troubleshooting
Provider Connection Issues
# Test provider connectivity
elephant config test-provider
# Reset provider configuration
elephant config reset-provider
# Check API key
echo $OPENAI_API_KEY # Should not be empty
# Verify model availability
elephant models list
Personal Model Not Loading
from elephant_agent import PersonalModel
# Reset model if corrupted
PersonalModel.reset()
# Reinitialize
agent.init(force=True)
# Verify model structure
model = PersonalModel.load()
assert model.is_valid(), "Model structure invalid"
Dashboard Connection Issues
# Check if dashboard is running
elephant dashboard status
# Kill existing dashboard
elephant dashboard stop
# Restart on different port
elephant dashboard --port 8080
# For remote access, use tunnel
ssh -L 3000:localhost:3000 user@remote-host
Performance Optimization
from elephant_agent import ElephantAgent
# Reduce model calls with caching
agent = ElephantAgent(
cache_responses=True,
cache_ttl=300 # 5 minutes
)
# Lower curiosity effort for faster responses
agent.set_curiosity_effort("low")
# Use smaller model for routine tasks
agent.set_model("gpt-3.5-turbo") # Faster, cheaper
# Batch questions
questions = [
"What's my next step?",
"Any blockers?",
"Energy check?"
]
responses = agent.ask_batch(questions)
Debugging
# Enable debug logging
export ELEPHANT_LOG_LEVEL=debug
elephant wake
# View logs
tail -f ~/.elephant/logs/elephant.log
# Check runtime state
elephant debug state
# Verify skills
elephant skills test filesystem